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1. INTRODUCTION 



TSX-Plus is a hi gh-p er f o rna nee , general purpose, time-sharing 
operating system for Digital Equipment Corporation PDP-11 and 
LSI-U computers. TSX-Plus provides the functionality of the DEC 
RT-11 operating system to up to 20 concurrent time-sharing users. 

TSX-Plus overlaps terminal interaction time, I/O wait time 
and CPU execution time for all jobs on the system. The result is 
a tremendous increase in the productivity of the computer system. 
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TSX-Plus is a general purpose time-sharing system. It can 
Itaneously support a wide variety of jobs and programming 
uages including COBOL-Plus, FORTRAN, BASIC, DIBOL, PASCAL, 
MACRO, TECO and KED. TSX-Plus is in use in educational, 
ness, scientific and industrial environments 
urrently support commercial users doing 
essing, engineering users performing 
system programmers doing program development 



scientific 



It can 
transaction 
processing. 



to the basic 

features such 
a shared file 
communi ca t i on 
tor system; command files with parameters; 
e accounting system. 
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RT-11 functionality, TSX-Plus 
as a transparent line -printer 
record locking facility; an 

facility; a program performance 
and a logon and 



TSX-Plus will 
rv management 



run on any PDP-11 or LSI-11 computer that has 
facilities and at least 96Kb of memory. The 
en must also have a disk suitable for program swapping (the 
ping disk can also be used for regular file storage as well), 
-sharing lines can be connected to the system through DL-11 or 
1 communication devices. Both hard-wired and dial-up lines 
supported by TSX-Plus. 



nd PDP-11 are trademarks of Digital 



*DEC, RT-11, CTS-300, DIBOL 

Equipment Corporation. 

**Unless otherwise indicated, all information applies to RT-11 and 

CTS-300. 
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2. BASIC OPERATION 



2 . 1 Logging On 
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is generated, lines can be set up so that they 
initiated when TSX-Plus Is started. If this is 
message "TSX-Plus version x.y" will be printed 
when TSX-Plus is started. Lines which are not 
automatic start feature must be initiated by 
return at the terminal. 
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ted requiring log on authorization, the 
11 be printed. The user should respond 
a comma, and a programmer number 
urn. TSX-Plus will then request the 
sons the password is not printed at the 
After the p ro ject -programmer numbers 
SX-Plus checks them for validity and, 
sage "Welcome to the system". TSX-Plus 
indicating It is waiting for a command 
command file that was specified by the 



ommand file contains initialization commands for 
d by either leaving the line waiting for a 
a period is printed) or by starting execution of 
is possible for a command file to lock a program 
at if execution of the program Is terminated the 
lly logged off. Any characters typed at the 
the execution of a start-up command file are 
ontrol-C will not abort a start-up command file. 

The following example illustrates a typical log-on sequence. 
The information typed by the user is underlined. 



( :: a r r 1 a g e return pressed) 
T S X - P 1 u s v e r s 1 o n 1 . 5 
26-Sep-80 11:45:27 
Logon please: A 1 3 , 2 I 7 
Pa s q word : MYP ASS ( pa s sword entered but not printed) 

■/• e 1 c m <■"' T. r, t It n system 

.(TSX-Plus is now waiting for a system command) 

A user may adopt a new password while logging on. To do 
this, enter a slash and the new password Immediately after typing 
the old password. The new password must then be used for future 
logons. Passwords may be from 1 to 7 characters In length and 
must be composed only of letters and digits. The following 
example shows the password being changed from "OLDP" to NEWP . 
Note that neither the old nor the new password is echoed. 



(carriage return pressed) 
TSX-Plus version 1.5 
26-Sep-80 4:17:43 
Logon please; 107 »24 
Password; OLDP/NEWP 

Welcone to the system 



If the T S X - PI 11 R r. 
authorization is not 

please:" it will either start executing 
will sinply print a 
G n t (? r e d . 



■^t en is generated so that logon account 
required, then instead of saying "Logon 

a start-up connand file or 
for a svsten connand to be 



period and wait 



The OFF systen connand (described below) is used to log off 
tin <?. sharing line. 
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2 . 2 Cont rol Characters 

The following characters nay be used to control terralnal 
operations. They are entered by holding down the "CTRL" key while 
pre ?i sing the selected character. 



CTRL-U - Dnletos the current input line. 



CTRL-0 - 



Causes suppression of pr ogrnrr. output to the 
ternlnal until one of the following conditions 
occurs : 



1 ) A second CTRL-0 is t: y p c d 

2 ) A r e t u r n to r o n i t o r o c. curs 

3) The runninp, program issues a .RCTRLO EMT. 

CTRL-S - Teinporari ly suspends output to the terminal until 
CTRL-Q Is typed. CTRL-S has no special effect if 
SET TT I^OPAGE has been used. 

CTRL-Q - Resumes printing on the terminal from the point at 
which printing was previotisly suspended by CTRL-S 
or end of page (see SET TT LEMCTU command). CTRL-Q 
has no special effect if SET TT N'OPAGE has been 
used . 

CTRL-R - Causes the current characters in the TTY input 
buffer to be typed out. This can be used to check 
the actual status of an input line when rubout 
editing has been done on the line. 

CTRL-C - Interrupts the current program and returns control 
to the keyboard monitor. If the running program is 
not waiting for input, two successive CTRL-C's are 
required to interrupt its execution. 

CTRL-Z - Indicates end-of-flle when input is being read from 
device "TT". 



CTRL-I - Equivalent to T A R . 

CTRL-W - Used to switch to a TSX-Plus virtual line. (See 
chapter on virtual lines.) 



2, 3 Keyboard CoinmandB 

The TSX-Plus command Interpreter is aomewhat more powerful 
and flexible than the standard RT-11 command Interpreter. When a 
system command line Is typed In, TSX-Plus performs the following 
steps while trying to Interpret It: 

1. If the command line begins with an at sign ("0"), 
TSX-Plus Interprets the command as a command file 
execution. If no device Is specified with the command 
file name, device DK: Is assumed. See the chapter on 
command files for further Information on them. 

2. TSX-Plus next attempts to identify the command as a 
standard system command such as COPY, RUN, EXECUTE, etc. 
Commands may be abbreviated to the minimum number of 
characters that uniquely specify the name. Thus "COP" 
would be an acceptable abbreviation for COPY, but "CO" 
would not because it could mean COPY or COMPILE. "COPX" 
also would not be identified as a system command. 

3. If the command cannot be identified as a standard system 
command, TSX-Plus tries to find a command file on device 
"DK:" that has the same name as the command keyword. If 
no such command file is found on "DK:", TSX-Plus looks 
for the command file on device "SY:". If such a command 
file is found, its execution is started. When a command 
file is started in this fashion (rather than explicitly 
specifying an at-sign before its name), the command file 
listing is suppressed as if an implied "SET TT QUIET" 
command was executed during command startup. This 
implied listing suppression is temporary in effect and 
applies only to the command file started in thisf 
fashion. See example 5 below. 

4. If a system command file cannot be found, TSX-Plus looks 
for an executable program (SAV file) on device "SY:" 
that has the same name as the command keyword. If such 
a program is found its execution is started as if there 
were an "R" command in front of the program name. Note 
that RT-11 and TSX-Plus allow a line of text input to be 
passed to a program by specifying it on the RUN command 
after the program name. TSX-Plus also allows this to be 
done with the "R" command as well as with an implied "R" 
command line when the program name is specified as the 
command keyword. See example 6 below. 

Examp les ; 

1. Run a program named "DUMP" on device "SY:". 
.R DUMP 

2. Run a program named "PAYROL" on device "DXl:". 



.RUN DXl: PAYROL 
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3. Execute a command file named "PURGE" on device "DK:". 

.(5PURGE 
A. List all files on "RKl:" 

.DIR RKl : 

5. Start a command file named "LOADIT" on "SY:" and pass it 
the parameter string "PR0G2". 

.LOADIT PR0G2 

6. Execute the program "PIP" on "SY:" and pass It the Input 
line "A.TMP=B.TMP" . 

.PIP A.TMP=B.TMP 
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2'3.1 The "ACCESS" Command. The ACCESS command is used to restrict 
user file access to a particular set of files or devices. Refer 
to the TSX-Plus System Ilanager's Guide for further information 
about this command. 



. 3. 



The "ASSIGN" 



Command. The RT-11 ASSIGN command Is used to 

A 



associate a logical I/O device name with a physical device, 
frequent use is to assign FORTRAN I/O unit numbers to selected 
devices. The TSX-Plus ASSIGN command provides this facility in an 
identical fashion and also offers a useful extension. In addition 
to being able to specify a physical device name, the user nay 
specify a file name, extension, and size. 

To simply assign a logical device name to a physical device, 
the form of the ASSIGN command is the same as that under RT-11. 
For example, to assign the logical device name "BIN" to physical 
device "DXl" the command would be: 



ASSIGN DXl BIN 

To assign FORTRAN I/O unit number 1 to the teletype, the command 
v/ould be: ASSIGN TT 1 



If a file name and optional size is to be specified in addition to 
the physical device name, the file name and size follow the device 
name. For example, to assign FORTRAN I/O unit number 1 to a 
named "PAYROL" on device "DXO" with a size of 43 blocks, 
following command could be used: 



f i le 
the 



a file 



ASSIGN DX0:PAYROL[43] =1 

The following command would assign logical device "BIN" to 
named "PROGl" on the system device: 

ASSIGN SY:PR0G1=BIN 

It is also possible under TSX-Plus to assign a new logical 
name to a previously assigned logical name. The effect is to 
assign the new logical name to the same physical device that the 
previous assign was directed to. For example, the following 
sequence of ASSIGNs result in both logical devices "AA" and "BB" 
being assigned to "DLl". 

ASSIGN DLL A A 
ASSIGN AA BB 



A maximum of fifteen assignments nay 
given time for each user. 



be 



in effect 



at 



a ny 
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2.3.3 The "BOOT" Connand. The BOOT cor-.nand causes TSX-Plus to 
Ibort ""all currently runnlnp, jobs and to roboot RT- 1 1 . Unlike the 
RT-Il BOOT command no device or file na:->e r.nv he specified with 
the TSX-Plus boot command --it always r.iboots from the system 
(SY) device. Operator command privilege is required to use this 
command. The BOOT command is functionally equivalent to tlie $STOP 
command. 



2„3.A The "COBOL" Command. The Cr;BOL command is used to cause the 
COBOL-pT^ compiler to compile a COBOL source program. The 
default extension for COBOL source programs is "CBL", the default 
extension for COBOL object files is "CBJ". The COMPILE, LINK and 
EXECUTE commands may also be used to compile and/or execute COBOL 
programs as TSX-Plus will invoke the COBOL-Plus compiler and 
CBLIMK link program if the source program specified to compile has 
the extension "CBL" or the object program specified to link has 
the extension "CBJ". Switches that can be used with the COBOL 
command are listed below. 

Switch Meaning 

/CROSS Produce a cross-reference of the source program. 

/CREF (Equivalent to /CROSS). 

/ONDEBUG Compile the nro-nm for m-.o with the interactive debugger. 

/PRODUCTION Omit line number tracin- and subscript checking code. 

/ANSI Produce warning messages for any non-ANSI standard feature 

/LIST Produce a source program listing. 

/::ARR0W Format the cross-reference for 80 column display. 

/INFORMATION Print additional information at end of compilation. 

/CARD Source program is in card sequence format. 

/SEQUENCE (Equivalent to /CARD). 

/SUMMARY Print only error messages on listing device. 

/OBJECT:narae Specify name of object file. 

/ALLOCATE: size Specify size of object file. 

See the COBOL-Plus reference manwal for f u r t lv2 r information about 
this c ommand . 



2.3. 5 The "COMMENT" Command. This command may be used to place 
comments Inside command files. The form of the COMMENT command 
Is: 

COMMENT comments 
where "comments" may be any string of characters. 



2.3. 6 The "COMPILE" Command. The COMPILE command Invokes the 
appropriate language processor to compile the specified source 
file. The TSX-Plus COMPILE command Is the same as the RT- 11 
COMPILE command except that It also recognizes programs with the 
extension "CBL" as COBOL source programs and calls the COBOL-Plus 
compiler. When compiling a COBOL program, the switches that are 
legal with the COBOL command may also be used with the COMPILE 
command. It is also possible to explicitly specify that the 
COBOL-Plus compiler is to be called by using the "/COBOL" switch 
with the COMPILE command. 



2.3.7 The "COPY" Command. The TSX-Plus COPY command has the same 
form and options as the RT-11 COPY command. 



2.3. 8 The "DATE" Command. The TSX-Plus DATE command has the same 
form and options as the RT-11 DATE command. Operator command 
privilege is required to set the date. 



2.3.9 The "DEASSIGN" Command. The TSX-Plus DEASSIGN command is 
Identical to the RT-11 DEASSIGN command. It is used to 
disassociate a logical unit number assignment. 
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2» 3. 1 The "DELETE" Command. The TSX-Plus DELETE command has the 
sane form and options as the RT- 1 1 DELETE command. 



2.3.1 1 The "DETACH" Command. The DETACH command Is used to 
initiate execution of a command file as a "detached" job, to abort 
a detached job or to check the status of a detached job. The use 
of this command requires the user to be authorized to use detached 
jobs. J^r^ ro^t^-i ^^'>'' '^-^ iJ-^T^c^ £p^c,-..;c 

The form of the command used to start a detached job is: 



.DETACH file 



/ 



where "file" is the name of a command file which is to be started 
as a detached job. If a free detached-job line is available the 
file will be started and a message will be printed indicating on 
which line the detached job was started. Detached-job lines must 
be declared when TSX-Plus is generated. 

In the following example a command file named "CRUNCH" is 
started as a detached job. 

.DETACH CRUNCH 

Job started on line #3 



The form of the DETACH command used to abort a detached job 



1 s 



.DETACH/KILL line-number 

where "line-number" is the number of the detached-job line where 
the job is executing. 

The form of the DETACH command used to check the status of a 
detached job line is: 



.DETACH/CHECK line-number 

In response to this command TSX-Plus will indicate if 
still executingont he line. 



job is 



See the chapter on virtual lines and detached jobs for 
further information. 
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2.3.12 The "DIBOL" Coininand. The DIBOL command is used to compile a 
DIBOlT" s^rce program. The TSX-Plus DIBOL command has the same 
form and options as the RT-11 DIBOL command. 



2.1.13 The "DIFFERENCES" Connand. The DIFFERE;;CES connand is used 
" ^T"object files. The TSX-Plus DIFFERENCES 



to compare two source 
connand has the sane 



form and options as the RT-11 command. 



2.3.14 The "DIRECTORY" Connand. The TSX-Plus DIRECTORY command has 

the RT-ll DIRECTORY connand. 



L M O 



sane 



form and options as 



^•^•■L5. The "DISMOUNT" Connand. The DISMOUNT connand is used to 
tell TSX-P lus that it should stop doing directory caching on a 
particular device. The form of the DISMOUNT connand is: 

DISMOUNT ddu 

where "ddu" is the nane of the device. The only effect of the 
DISMOUNT connand is to cause TSX-Plus to stop doing directory 
caching for the device. Files on the device nay still be accessed 
after the DISMOUNT connand is issued. When one user issues a 
DISMOUNT connand, the device is dismounted for all users. An 
autonatic disnount is done when an IN IT or SQUEEZE connand is done 
on a device. 



2.3.16 The "DISPLAY" Connand. This connand can be used within a 
cor.nand f i le to cause a line of text to be displayed on the 
terninal when the connand is executed. This Is useful in command 
files that are not being listed to keep track of the progress 
through the command file. The form of the DISPLAY command is: 

.DISPLAY ccnnents 



where "connents 
terninal. 



can 



be 



anv text string to be displayed on the 
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2.3.17 The "DUMP" Connand. The TSX-Plus DUMP connand has the sane 
fnrn~and options as the RT- 1 1 DUMP connand. 



2.1.18 The "EDIT" Connand. The TSX-Plus EDIT connand has the sane 
Tolrn and options as the RT- 1 1 EDIT connand. 



2.3.19 The "EXECUTE" Connand. The TSX-Plus EXECUTE connand has the 

It will also 

COBOL source 

linker. 



sane forn and options as the RT- 1 1 EXECUTE coramand. 

with the extension "CBL" as 



recof^nize prograns 

and will invoke the COBOL-Plus conpiler and 



prograns 



Z.3.20 The "FORM" Connand. The FORM connand is used to specify the 

used by subsequent spool files generated 



default forn nane 
bv t!"ie user. The 



to be 

forn of the FORM connand is: 



FORM nane 

where "nane" is the one to six character default forn nane to be 
used for all spool files generated by the user until another FORM 
connand is issued. See section 4.3 for further infornation. 
initial default forn nane for each user is "STD". 



'he 



In the following exanple a FORTRAN listing will be generated 
for printing on a forn called "2-PART". 

. FORM 2-PART 

. COMPILE/LIST TEST 

.FORM STD 



-12 



2.3.2 1 The "FORTRAN" Command. The TSX-Plus FORTRAN command has the 
sane Torra and options as the RT-11 FORTRAN command. 



2 . 1 . 2 : 2 The "HELP" Command. The TSX-Plus HELP command has the sane 
torn Hn d options as the RT-11 HELP command. 



2 . 3.2 3 The "INITIALIZE" Command . The TSX-Plus INITIALIZE command 
~~. t~he sane form and options as the RT-11 INITIALIZE connand. If 
the :!()UNT connand was used to nount the device being Initialized, 
the device Is automatically dismounted before the Initialization 
takes place. 



2 . 3 . 2 . 4 The "KILL" Command. The KILL command can be used to kill a 
tine sTi" a ring job. This has the effect of aborting the execution of 
the job and forcing the logoff of the line. Operator command 
privilege Is required to use the KILL command. The form of this 
connandis: 

.KILL line-number 

where line-number is the number of the job to be killed. 



2.3.2 5 The "LIBRARY" Command. The TSX-Plus LIBRARY command has the 

sane form and options as the RT-11 LIBRARY command. It also can 

be used to build COBOL-Plus object program libraries; see the 

COBOL-Plus reference for further information. 



2 .3.2 6 The "LINK" Command. The TSX-Plus LINK command has the same 
forn "and options as the RT~ 1 1 LINK command. It will also 
recognize object files with the extension "CBJ" as COBOL-Plus 
object files and will invoke the COBOL-Plus link program (CBLINK). 
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2.3.27 The "MACRO" Command. The TSX-Plus 
sane form and options as the RT-11 MACRO 



MACRO command 
command . 



has the 



2.3.28 The "MEMORY" Command. The MEMORY command is used to control 
the amount of memory made available to a job. When a job 
Initially logs on It receives a default memory size allocation 
that was set by the system manager. The MEMOPvY command can be 
used to change the allocation for the job. The form of the ME!;ORY 
c onmand 1 s : 

MEMORY nn 

Where "nn" is the number of k-bytes of memory to be allocated for 
the job. The maximum memory size that a job may expand to is set 
by the system manager but is never greater than 56. When a 
running program performs a .SETTOP emt the top of memory address 
corresponds to the size last specified by a MEMORY command. Note 
that .SETTOP emt ' s do not actually affect the amount of memory 
allocated to a job -- only the MEMORY command does that. 

If the MEMORY command is entered without specifying a size, 
the current memory allocation for the job is displayed. See also 
the description of the SHOW MEMORY command. 



2.3.29 The "MONITOR" Command. The MONITOR command is used to cause 
TSX-Plus to begin doing a performance analysis. See chapter 9 for 
complete information about the TSX-Plus performance analysis 
feature. The form of the MONITOR command is 

MO NITOR base-address, top-address[ ,cell-size]/s witches 

where "base-address" Is the lowest address in the program region 
being monitored, "top-address" is the highest address in the 
region, "cell-size" is the number of bytes to group per histogram 
cell. The only available switch is "/I" which, if specified, 
causes I/O wait time to be included in the analysis. 
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MOUNT command is used to tell 
a f i le-s t ruct ured device is to have its directory 



2.3.30 The "MOUNT" Command. The 



T S X - P 1 u R t h a t 

cnched. Directory caching is a technique that spepris un '. iln 
lookups by keeping information about files in me;,iory so Lb it i !. is 
not necessary to access the directory on the device e a cli t i ;r. e a 
file is opened. The form of the MOUNT command is: 



01 



ddu 



w h e r c; 


"ddu" is a dev 


ice name 


such as 


"DLl". The only c 


f f e c t 


o t 


the 


'lOUNT command 1 


s to tell 


TSX-Plus that It should do 


directory 


each! 


ng for the device being 


mounted. 


If directory cachi 


ng is 


n o t 


w a n 1 1; 


d it is quite 


possible 


to mount 


a device and access 


f 11 o 


S .■'i !1 


1 t w 1 


t h o u t using the 


MOUNT command. 


Once a MOUNT co 


m n a n d 


i s 


issue; 


d , directory 


caching 


is enabled for all users w 


ho access 


files; 


on the devl ce . 


If the 


MOUNT 


command is used 


to cause 


TSX-Plus to do directory 


cachl ng 


for a device , it is 


c r uc 1 


ally 


i mp or 


tant that the 


DISMOUNT 


comman 


d (see below) be 


used 


t o 


dismount the device before 


a new 


disk is mounted on 


the 


same 


drive 


If a new pac 


k is mo un t e d wl 


thout telling TSX- 


Plus, 


i t 


would 


try to access files 


on th 


e new pack according 


to t 


heir 


posit; ions on the old 


pack whose directory information is 


1 n 


its 


d i r e c: 


tory cache. 













Directory caching has a dramatic speed effect on flic lookups 
but does not speed up file enters, deletes or renames. ihis is 
because TSX-Plus always updates the directory on the device when 
it is altered. The maximum number of devices whose directories 
may be cached and the number of file entries that are kept in the 
directory cache are specified when TSX-Plus is gc ne r a t o d . The 
systeri disk is always cached and need not be mounted. 

E X a m j^i 1 e : 

MOUN'T DL2 



2.3.3 1 The "OFF" Command. The OFF command is used to log off a 
Terminal. It is also used to release a virtual line (see the 
discussion of virtual lines on page 17). On dial-up lines, an 
automatic log off is performed by TSX-Plus if. the telephone 
connection is broken. The accumulated connect time and CPU time 
used during the session are printed during the logoff processing. 



Examp 1 e : 
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. OFF 

cF^ect time = 01:43:00 CPU-00 : I 2 : 3 . 7 



2,3.32 The "OPERATOR" Command. The OPERATOR command is used to 
send a message to the terminal which was specified to be the 
operator's console when TSX-Plus was generated. The OPERATOR 
command works like the SEND command, but it is not necessary to 
know the line number of the operator's terminal. The form of the 
OPERATOR command is: 

OPERATOR message 

Examp le : 

Send a disk mount message to the operator: 

OPERATOR PLEASE MOUNT PAYROLL MASTER DISK ON RKl 



command is used within 
(see chapter 9) to cause a pause in processing the 



2.3.33 The "PAUSE" Command. The PAUSE 



command files 

file,. The form of the PAUSE command is: 

PAUSE comments 

where "comments" may be any string of characters. When a PAUSE 
command is encountered within a command file, the PAUSE command is 
printed on the terminal followed by ">>". Execution of the 
command file is then suspended unt i 1 ca r r i age return is pressed. 
This gives the operator an opportunity to perform manual 
operations such as mounting disks or tapes. 



2.3.34 The "PRINT" Command. The TSX-Plus PRINT command 
same~o7m~and options as the RT-11 PRINT command. 



has the 
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2.3.35 The "R" Connand. The "R" command is used to start execution 

is searched for the 



of a 
program is 



whi c h 



program. The default device 

"SY:"; a different device name may be specified with 
the name of the program. A line of input may be passed to the 
program by specifying it as part of the "R" command following the 
program name. If this is done the program will receive the text 
string as its first line of input and will receive control-C 
Its second line of input. 



a s 
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thi 
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ecified following the "R" command 
s switch causes the program that is 
o the timesharing line so that when 
s automatically logged off. If the 

a command file the command file is 
is started and any additional 
e is ignored. The mo st frequent 
rt-up command files where a line is 
a particular pro j; ram. If a locked 
ogram, the program that was chained 

program. See example 4 below. 
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Exam]-) 1 e s : 
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1. Run tlic program naned "DUIIP" on device "SY:". 

.R nijMP 

2. Run the pro;-; ran naned "PLP" on "SY:" and pass to it the input 
line "A.TMP=B.TMP . 

.R PIP a.tmp = b.t:ip 

3. Run the proj^ran naned "SA:lPLr:" on "RK2:". 
. R RK2 : SA;IPLK 

4. Start the execution of BASIC and lock it to the line. 

.R/^.OCK BASIC 

3. Start a prograri naned PLA.,'!-^ and allow it to 
use s i n p, 1 e character activation node. 

. Ri;:;/ si.;cLK PhA;;K 

() . Start a p r o i^ r an naned T [\ I A L in d e 1) u ,q; node so that 
i t w 1 11 be run under T S J T . 

. ru:;/ijhbi:g TiUAL 

^TSX-0DT-V3'^ 



2 . 3 » 3 h The "RE:;a:1E" Connand. The TSX-Plus RENAME connand has the 
sane Forn and options as the RT- 1 1 RENAME connand. 



2 . 3 „ 3 7 The "RESET" Connand ♦ The RESET connand can he used to reset 
the sy s t en usa~fe statistics that are displayed with the SYSTAT 
connand. This is useful when you want to nonitor syster.i 
perfornance during a particular part of the day. Operator connand 
p r i V i 1 e f^ o is required, to use the RESET connand. 
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2.3.38 The "RUN" Connand. The RUN command is Identical to the "R" 
command except that the default device Is "DK;" Instead of "SY:". 
See the description of the "R" command for Information about 

available switches. 



2.3,. 3 9 Tlie "SEND 



Connand. The SENT connand is used to send 
nes sages between tine sharing, terminals. The form of the command 
1 s : 



S E :; 1) , L i n e ->' n e s s a <^ e 

where line-.* is the number of the line to which the message is to 
be sent. If no line nunber is specified, the message is broadcast 

to nil logged-on lines. 

E X a n p 1 e s : 

1 . Send a :: o s s ri g o to all 1 o g g e d - o n users: 
SE:n) BOB-ARE YOU LOGGED ON? 

2 . Send a n e s s a g e to line nunber 2 : 

SE:;n,2 will you be on tonight? 

When a SEN'D nessago is printed at a terminal, the message Is 
preceded by the nunber of the line that originated the message. 
For Gxanpie, a message from line 1 might be printed as follows: 

*0 1* BOB-ARE YOU LOGGED ON? 



2.3., 4 The 



"SET" Connand. The SET connand is used to set various 

The general forn of the SET 



options controlling systen operation, 
connand is: 





.SET device option 




As with standard RT 


spec 


ify options for device 


wel 1 


as setting certain sy 


c h a i: 


acteri sties. \-Jhen use 


h a s 


the sane forn as 


( t h e 


y are specified in the 


cop y 


of the device handl 


e f f e 


c t of t li e connand bo 


c h a n 


gos the parameter b 


make 


the change to the cop 



-11, the TSX-Plus SET command is used to 
s such as line-printers, card-readers as 
stem parameters such as terminal control 
d to set device options, the SET command 
under RT-Il and may set the same options 
handler). The SET command causes the 
er on the disk to be altered so that the 
cones "permanent" (until another SET 
ack). The SET command also attempts to 
V of the handler that is in memory with 
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TSX-plus. If the handler is Idle when the SET is done, the change 
will be nade; otherwise, a warning message will be printed and the 
running copy of the handler is not altered. Operator command 
privilege is required to set an option in 



device handler. 



2 . 3 . A . 1 Options for the "SET TT" command 

The torn of this SET command is "SET TT option" to turn an 

option on and "SET TT NO option" to turn the option off. A few 

options require a numeric parameter, In which case they are 
specified as "SET TT op t 1 on= va 1 ue " . 



OPTION 



MEANING WHEN SET ON 



SCOPC The terminal Is a CRT device. Setting this option on 
has two effects: 1) Pressing the rubout key causes a 
backspace-space-backspace sequence to be echoed, erasing 
the previously typed character. 2) TSX-Plus counts the 
number of lines of output sent to the terminal. When as 
many lines have been sent as the screen size, TSX-Plus 
suspends output to the terminal (just as If CTRL-S had 
been pressed). Output may be continued by pressing 
CTRL-Q. This feature may be disabled by setting the 
page length to zero lines. See the "LENGTH" option 
below . 



ECHO 
LC 



FORM 



Causes characters to be echoed to the terminal. 

Allows lower case characters to be passed to a program. 
If LC is set and bit 14 of the job status word is set to 
1, input of lower case characters from the terminal will 
be passed to the running program. Otherwise, lower case 
characters are translated to upper case. 

Causes form feed (FF) characters not to be converted to 
line feeds. FORM should be set on with terminals whose 
hardware can respond to form feed characters. If set 
off, form feed c'naracters are replaced by an appropriate 
number of line feed characters. 



AB 



PAGE 



Causes TAB characters 
TAB should be 



not to be converted to multiple 

terminals whose 



spaces. iAn snouia ne set on with 
hardware can respond to TAB characters. If set off, TAB 
characters are replaced by an appropriate number of 
spaces v;hen being sent to the terminal. 

Allows CTRL-S and CTRL-Q characters to suspend and 

restart terminal output. If set off, CTRL-S and CTRL-Q 

have no special effect and are passed directly to the 

running program. 
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HOLD 



May be used with VT50 and VT52 terminals to set "hold 
screen" node on. This allows the SCROLL key to control 
output. Generally, the normal TSX-Plus end of page halt 
for scopes is more convenient than hold screen mode. 
The HOLD option may also be used with terminals other 
than VT50s. In this case, when a form-feed character Is 
sent the terminal's bell Is rung and output Is 
suspended. Output Is restarted when CTRL-Q is typed. 
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Setting the QUIET option on suppresses the listing of 

command files as they are being executed. See the 

chapter on command files for additional information on 
controlling their listing. 

Setting the FORMO option on causes TSX-Plus to advance 
to the top of the page on the terminal when a write Is 
done to the terminal with a block number of zero. This 
is convenient when producing multiple program listings 
to cause each listing to begin at the top of a new page. 



LENGTH The LENGTH option is used to set the number of lines on 
a page. The form of this option is: 

"SET TT LENGTH=value" 
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FILLER 



The second use of the page size is to determine when to 
suspend output when printing on a CRT (SCOPE) terminal. 
When TSX-Plus prints the last line of the page on a CRT 
terminal, it suspends output and waits for the user to 
press CRTL-Q. This automatic suspension can be 
suppressed by setting the page size to zero lines. 

The FILLER option is used to set the number of delay 
(filler) characters that are to be transmitted after 
carriage-return/line feed. The form of this option is 
"SET TT FILLER=valuel , value2 , value3" . 



WAIT 



V T 1 



VT5 



whe re 

valuel = Number of de 1 ay char ac t er s to send. (Specify 

In dec! nal ) . 
value2 = Character after which delay characters are 

required. (Specify in octal). Carriage-return = 

15, line feed = 12. 
value3 = Character to use as a filler. (Specify in 
octal . ) 

Value 2 and value 3 nay be omitted from the command if 
only value 1 needs to be changed. The appropriate sets 

are listed below. 
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Normally TSX-Plus blocks the execution of a program that 
does a .TTYIN EMT if no activation character has been 
received even if the program sets bit 6 in the Job 
Status Word which is supposed to mean that the program 
can do non-blocking .TTYIN character tests. This was 
done to prevent programs from burning up CPU time by 
constantly looping back to test for terminal input. If 
the NOWAIT option Is specified with the SET TT command, 
TSX-Plus will honor bit 6 in the Job Status Word and 
allow the program to do non-blocking .TTYIN's. 

Tells TSX-Plus that the terminal being used is a VTIOO 
(which must be operated in VTIOO mode — not VT52 
compatible mode) and also has the effect of SET TT 

SCOPE, TAB, PAGE, NOFORM, LENGTH=24. 

Tells TSX-Plus that the terminal being used is a VT52 
and also has the effect of SET TT SCOPE, TAB, PAGE, 

NOFORM, LENGTH=24. 
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LA36 Tells TSX-Plus that the terminal being used is an LA36 
and also has the effect of SET TT NOSCOPE, NOTAB, 
NOFORM, NOHOLD, LENGTH-66. 

LA120 Tells TSX-Plus that the terminal being used is an LA120 
and also has the effect of SET TT PAGE, TAB, FORM, 
NOSCOPE, NOHOLD, LENGTH-66. 

ADM3A Tells TSX-Plus that the terminal being used is a Lear 
Siegler ADM3A and also has the effect of SET TT SCOPE, 

NOTAB, NOFORM, NOHOLD, LENGTH=»24. 

HAZE LIT NE Tells TSX-Plus that the terminal being used is a 
Har-eltlne brand terminal and has the effect of SET TT 
SCOPE, NOTAB, NOFORM, NOHOLD, LENGTH=24. 

DIABLO Tells TSX-Plus that the terminal being used is a Xerox 
Diablo terminal and has the effect of SET TT NOSCOPE, 
NOTAB, FORM, NOHOLD, LENGTH=66. If you are doing 
plotting or proportional spacing printing, you should do 
a SET TT TAB command. 



OUMK 



Tells TSX-Plus that the terminal being used is a Qume 
brand terminal and has the effect of SET TT NOSCOPE, 
NOTAB, FORM, NOHOLD, LENGTH=66. If you are doing 
plotting or proportional spacing printing, you should do 
a SET TT TAB command for the terminal. 



All of these options can be given Initial settings for each 
line when the TSX-Plus system is generated. Each time a user logs 
onto a line, the initial option settings are used. The options 
may be altered by using the SET command, but when the user logs 
off, the options revert to their initial (sysgen) setting. When a 
user initiates a virtual line, the initial flag settings for the 
virtual line are copied from the current flag settings for the 
user. Subsequent flag changes for a virtual line do not affect 
flag settings for the user's other lines. 



2.3.40.2 Options for the "SET CCL" command 



There are two types of system 
such as RUN, SF^T, ASSIGN and high 
COPY, DELETE, and DIRECTORY. Low 
directly by TSX-Plus. High leve 
into the appropriate low level comm 
are executed. The set of high 
Concise Connand Language (CCL). Th 
to observe the low level commands t 
CCL connands. There are two option 
CCL TEST" and "SET CCL NOTEST" 
node,, it will print at the terminal 



commands, low level commands 
level commands such as EXECUTE, 

level commands are executed 
1 commands are first translated 
ands and then these commands 

level commands is known as the 

e "SET CCL" command can be used 

hat are produced by translating 

s to the SET CCL command: "SET 

When TSX-Plus is in CCL TEST 

the low level commands that 
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are generated when a CCL command is entered. In this mode the low 
level commands are only printed and not executed. The "SET CCL 
NOTEST" command turns this off and TSX-Plus goes back to executing 
CCL commands. Test mode is very useful if you are having trouble 
getting some complex CCL command to work and want to examine the 
low level commands that are being generated. 



2.3.41 The "SHOW" Command. The SHOW command is used to display 
Information about the state of the system. Each form of the SHOW 
command is described below. 



2.3. 41.1 SHOW ASSIGNS. The SHOW ASSIGNS command displays 
information about all logical device assignments that are 



currently in effect. 



2.3.41.2 SHOW DEVICES. The SHOW DEVICES command displays 
Information about which devices were specified as being available 
when TSX-Plus was generated. 



2.3.41.3 SHOW JOBS. The SHOW JOBS command displays information 

aboift JoFs that are currently logged onto the system. The 

Information displayed by this command is identical to that 

displayed by the SYSTAT command. 



2.3.41.4 SHOW MEMORY. The SHOW MEMORY command displays information 
aboirt memory usage including the total installed memory on the 
machine, the size of TSX-Plus and handlers, the memory space 
available to user jobs and the current job memory allocation and 
maximum authorized size. It also lists the size of the swappable 
job context area which is a system table associated with each job. 



2.3.41.5 SHOW QUEUE. The SHOW QUEUE command displays information 
rboTit print files in the spool queue. The following information 
is displayed for each print file in the queue: name of the device 
the file is queued for; an asterisk if the file is currently being 
printed; the name of the file if a file name was specified with 
the enter -- otherwise the name of the program that created the 
file; the name of the form on which the file Is to be printed; the 
number of blocks in the file remaining to be printed — this will 
decrease as the file is printed. 
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2.3,41.6 SHOW USE. 



usage statistics for 
statistics displayed 



The SHOW USE command causes display of the 
the current job since the logon. The 
include the connect time and CPU time. 



2.3.42 The "SQUEEZE" Command. The TSX-Plus SQUEEZE command has the 
sane form and options as the RT- 1 1 SQUEEZE command. If the riOUNT 
command has been used to mount the device being squeezed, it is 
automatically dismounted before the squeeze takes place. 
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The information displayed for running jobs consists of one 

line per job. The line number is printed first, followed by an 

asterisk if the line is the one you are logged onto. A letter "V" 

is printed next if the line is a virtual line; a letter "D" 
indicates the line Is a detached job line. A t wo-cha rac t er state 

code is printed next Indicating the current state of the job. The 
state codes and their meanings are as follows: 
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code: meanl ng : 

Waiting for Input from the terminal. 

Waiting for the terminal to print output. 

Program is running. 

Job is doing a timed wait (.TWAIT). 

Job is waiting for access to a shared file. 

Job is waiting for a message. 

Job is waiting for I/O to finish. 

Job is waiting for access to USR file management module 

Job is waiting for free spool block or file entry. 

The characters "-SWP" are printed following the state code if the 
job is currently swapped out of memory. 

The number of K-bytes of memory space used by the job is shown 
next, followed by the connect time and CPU time used so far by the 
job. The name of the program being run by the line is shown next. 
If the job logged on the P ro je ct , P rog rammer number is listed last. 



TI 


TO 


RN 


SL 


SF 


MS 


10 


US 


SP 



Examp 1 e t 



. SYSTAT 

Uptime: 04:27:32 

System use: Run=61%, I /0-wai t = 1 2% , Swap-wai t =5% , Idle=22% 

I/O activity: User 1/0=28%, Swapping 1/0=11% 

31:00 CPU=00:01:1A 
12:00 CPU=00:17:03 
04:00 CPU=00:02:17 



1* 


10 11KB 


2 


RN 36KB 


6 V 


RN 20KB 


7 D 


MS-SWP 20KB 



Connect=00 
Connect = 01 
Connect=00 
Connect=01:00:00 CPU=00:23:13 



TECO 
COBOL 
KED 
RTSORT 



PPN=3,4 
PPN=5 ,9 
PPN=5, 9 



2.3.44 The 



"SPOOL" Command. The SPOOL Command is used to control 
the operation of the spooling system. It may only be used if 
spooling is specified when the system is generated. The form of 
the SPOOL command is: 



.SPOOL device, function, parameter 

Where "device" is the name of a device that was specified to be 
spooled when the system was generated. "Function" denotes what 
function is to be performed and "parameter" provides additional 
information for some functions. See Chapter 4 for further 
information on the SPOOL command. Operator privilege is required 
to be able to use this command. 
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2.3.45 The "TIME" Command. The TSX-Plus TIME command has the same 
"form and options as the RT-11 TIME command. Operator command 
privilege Is required to set the time. 



2.3.A6 The "TYPE" Command. The TSX-Plus TYPE command has the same 
form and options as the RT-11 TYPE command. 



2.3.47 The $STOP" Command. The $STOP command is used to halt the 
execution of TSX-Plus and to rebootRT-11. 

$STOP 

The SSTOP command forces an immediate logoff of all users before 
stopping TSX-Plus. Operator privilege is required to be able to 
use this command. 



2.3.48 The "SSHUTDOWN" Command. The $S1IUTD0WN command is similar 
to the $STOP command in that it is used to stop TSX-Plus and 
return control to RT-11. However, it differs from $STOP in the 
manner in which it stops TSX-Plus. $STOP forces the Immediate 
logoff of all users; $SHUTDOWN does not. Rather, It sets a flag 
which prevents any new users from logging on and then waits for 
all logged on users to log off. When the last user logs off, 
TSX-Plus is stopped and control returns to RT-11. The form of 
this command is: 

$SHUTDOWN 
Operator privilege is required to be able to use this command. 
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2. 4 RT-1 1 Comnands Not Supported by TSX-Plus 



The following keyboard co nn and s are not supported by 
TSX-Plus: REENTER, CLOSE, START, SAVE, DEPOSIT, EXAMINE, BASE, 
GET,, LOAD, UNLOAD, GT ON/OFF. 
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3. VIRTUAL TIMES}IARI:JG LINES AND DETACHED JOBS 



3 « 1 Virtual Lines 

TSX-Plus provides a facility known as "virtual lines" that 
allows one tlnesharlng user to control several simultaneously 
running pro^rans from a single terminal. When a user initially 
logs onto TSX-Plus, that person is said to be connected to the 
primary line that is also called virtual line number (zero) for 
that user. At any time the user may switch to a different virtual 
line. This has the effect of logically disconnecting the 
timesharing terminal from the current virtual line and 
reconnecting it with a different logical line. 
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If a program is running at the time the switch is made, its 
utlon is not affected (but it is given a lower CPU priority). 
a running program that is not currently connected to a 
inal writes output to the terminal, the output is stored in a 
Inal output buffer. When this buffer is filled, the program's 
utlon is suspended (and the program is swapped out of core) 
1 the terminal is reconnected to the virtual line. When any 
ual line belonging to a user, but not currently connected to 
user's terminal, enters an input or output wait state the bell 
ung on tl\e user's terminal to signify that a virtual line 
s service. 
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A request to switch to a virtual line is indicated by typing 
rol-W (hold down CTRL key and press W) followed by a single 
t (do not hold down CTRL while typing the digit). The digit 
tlfles which virtual line the user wishes to access. This 

number represents the relative virtual line for that user. 
r users may be using virtual lines of the same number without 
llct. The CTRL-W digit sequence may be entered at any time 

in the middle of a line of input. The command takes effect 
dlately and leaves the old line in an undisturbed state. 
Plus responds to CTRL-W, digit by printing "n>" on the 
inal, where "n" is the number of the virtual line that has 

beenaccessed. 



If a start-up command file was associated with the primary 
line, the same command file will be executed when the virtual line 
is initiated. If the LOGOM program is run as part of the start-up 
command file for a virtual line, it will automatically log the 
user on witli the same p r o j e c t -p r og r amme r number as was specified 
when logging onto the primary lines. 

The user logs off a virtual line by typing the "OFF" command 
while connected to the virtual line. When a user logs off a 
virtual line other than the primary line, that virtual line is 
returned to the pool of free lines and the user is automatically 
connected to the primary line. V/hen a user logs off the primary 
line, not only is the primary line released, but any virtual lines 
the user may have been using are freed, and the user is 
disconnected from the system. Note that it is possible (and 
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frequently desirable) to switch back and forth between the primary 
line and several virtual lines without logging off any. 

The total nunber of virtual lines and the naxinun number of 
virtual lines which any user nay utilize at a given time are 
specified when the TSX-Plus system is generated. If a user 
attempts to log onto a virtual line and all the virtual lines are 
busy orthe user is already connected to the maximum number of 
virtual lines, TSX-Plus will not respond to the CTRL-W. 

Virtual lines are quite useful in situations where the user 
wishes to start a long "number crunching" job without tying up a 
line. Once the long job is started, the user can switch to 
another line. Programs that are running on a line that is not 
connected to a terminal are given a lower CPU priority than 
programs that are on lines connected to terminals. This means 
that the low priority programs will run only when no high priority 
programs are running. 

3 . 2 Detached Jobs 

The TSX-Plus Detached job facility is very similar to the 
virtual line facility; they both allow a timesharing user to 
initiate execution of several simultaneously executing jobs. The 
major difference between detached jobs and virtual lines is that 
virtual lines allow a user to switch terminal communication 
between several running tasks, whereas detached jobs do not. 
Detached jobs operate more like a "batch" facility. ALL terminal 
input for a detached job must come from a command file. Any 
terminal output generated by a detached job is discarded. 



The differences between virtual lines and detached jobs 
summarized below. 



are 



1. Using virtual lines, terminal communication may be 
switched between several running jobs. A detached job 
must receive all its terminal input from a command file 
and any terminal output it generates is discarded. 

2. Virtual lines are "owned" by a physical line. When the 
physical line logs off, the virtual lines also log off. 
Detached jobs are not associated with any physical line. 
Once started, any or all timesharing users may log off 
without affecting detached jobs. 

3. Detached jobs may be started automatically when TSX-Plus 
is initiated. Virtual line jobs must be started by 
timesharing users after TSX-Plus is running. 

A. When a detached job reaches the end of its command file 
and asks for more terminal input, the job is aborted and 
the detached job slot is freed. Virtual lines wait for 
more input. 
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3.2 .1 The DETACH conmand 

The DETACH connand is used to start a detached job, check its 
status and abort the job. The system manager may restrict the use 
of the DETACH command to selected users. 

3 . 2 „ 1 . 1 Starting a Detached Jo b The form of the DETACH command 
used to start a detached job is: 

DETACH file-spec 

where "file-spec" is the name of a command file that is to be 
executed as a detached job. The default device is "DK:" and the 
default extension is ".COM". V7hen a request is made to start a 
detached job TS)v-Plus searches for a free detached job slot. The 
total number of such job slots is established when TSX-Plus is 
generated. If a free slot is found the job is started and a 
message Is printed saying which job slot was used. This number 
may be used later to reference the detached job. 



E X a n r> 1 e s : 



1. Start a command file named "PURGE" as a detached job. 

. DETACH PURGE 
Job started on line 7/4 

2. Start a command file named "RK 1 : STATS . NEW" . 

. DETACH RKl ; STATS .NEW 
Job started on line #5 



3.2. 1.2 Checking the status o f a_ detached job. 

The form of the DETACH command used to check the status of a 
det^^ched job is: 

.DETACH/CHECK line-number 

vjhere "line-number" is the job slot number listed when the job was 
started. 

Examp 1 e s : 



1. Check the status of the job on line //4. 

. DETACH/ CHECK 4. 
Line is active 

2. Check the status of the job on line //5. 

. DETACH/CHECK 5_ 
Line is free 
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3 « 2 . 1 . 3 Abor ting a_ detached job 

The forn of the DETACH command used to abort a running 
detached job isJ 

DETACH/KILL line-number 

where "line-number" is the job slot number listed when the job was 
started. 

Example: 



1. Kill the job on line //4. 

. DETACH/KILL _4 
Job aborted 



3.2. 2 Detaclied Job Control Emt ' s 

TSX-Plus provides a set of emt ' s that can be used to control 

the operation of detached jobs. Using these emt's it is possible to 

start a detached job, kill a detached job and check the status of a 
det£iched job. 

3.2.2.1 Starting A Detached Job 

This emt can be used to start the execution of a detached job. 

Theformoftheemtis: 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 0,132 

.WORD .name- address 

where ".name-address" is the address of an area containing the 
name of the command file to be started as a detached job. The 
command file name must be stored in ASCIZ form and may contain an 
extension. If a free detached job line is available, the 
specified command file is initiated as a detached job and the 
number of the detached job line is returned in RO. 

errors: Code Mean! n g 

1 ■ No free detached job lines 
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3.2.2.2 Ki lllng A Detached Job 

This ent nay be used to abort a detached job. The form of 
the o n t is: 

e:it 375 

with. RO pointing to the following argument block: 

.BYTE 2,132 

. WORD . job-nunber 

where ".job-nunber" is the job number of the detached job to be 
ki 1 led. 

errors: Code Meaning 

1 In va 1 1 d job numbe r 



3.2.2.3 Checking The Status Of A Detached Job 

This emt nay be used to check the status of a detached job. 

The form of the ent is: 

EMT 375 
with RO pointing to the following argument block: 

.BYTE 1,132 

.WORD . j o b - n un b e r 

where ".job-nunber" is the number of the detached job to be 
checked. If the detached job is still active the emt returns with 
the carry-flag cleared. If the detached job has terminated and 
the detached job line is free, the emt returns with the carry-flag 
set. 
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4. DEVICE SPOOLING 



4 . 1 The C oncep t of Device Spooling 

Device spoolinp, is a technique that provides nore efficient 
use of slow peripheral devices by buffering data directed to the 
slov; devices to a high speed disk file where it is stored; later 
it is processed by the. slow speed device without holding up the 
operation of the progran that is generating the data. TSX-Plus 
optionally provides autonatic spooling to output devices such as 
printers, card punches and plotters. Output nay also be spooled 
to a timesharing terninal if an appropriate device handler is 
provided. Several devices nay be spooled on a systen. 
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a running progran directs output to a 
Is diverted by TSX-Plus to a spool disk 
n a spool control table indicating a spoo 
00 led device. When the spooled device be 
e is copied by TSX-Plus to the devi 
is autonatic and the user does not have 
operation. In fact a user can run p 
r then to be printed. Devices that are 
clared when the systen is generated. 

ed device handlers such as LP nust be set 
operation for tlien to work properly wl 



This can 



be done with the SET conn and. 



spooled device, 
file. An entry 
1 file is ready 
come s free , the 
ce . All of the 
to be concerned 
ro grans without 
to be spooled 



to the "HANG" 

th the TSX-Plus 

Fo r exanp 1 e : 



SET LP: HANG 

The SET conn and need only be issued once as it sets flags 
cop>' of the handler on the disk. 



1 n 



the 



4 . 2 Pi rec ting O utput t o Spooled Devi ces 



Output is directed to a spooled device in exactly the sane 
wav it would be directed to the sane device if it were not 
spooled. For exanple, if the line printer (LP) were spooled, the 
following connands would send a FORTRAN listing to the printer: 

.R FORTRA 
*TEST .LP: =TEST 



The nane of a spooled device nay be used in a MACRO .ENTER 
connand the sane as a non-spooled device would be. 

Any nunber of users nay be writing output to a spooled device 
sinultaneously without conflict. TSX-Plus stores the output from 
each user in a separate spool file and prints then in an orderly 
fashion. A user nay direct output through several I/O channels to 
the sane or different spooled devices. Output records directed 
through separate channels to the sane device are separated into 
difl'erentspool files. 
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The total number of spool files that may be in existence is 
also specified when TSX-Plus is generated. A spool file is 
created when an I/O channel is opened to a spooled device; the 
file remains in existence until all of the output is finished 
being processed by the spooled device. If a channel is opened to 
a spooled device and the maximum number of files is already in 
existence, the execution of the program is suspended until a spool 
fileisprintedanddeleted. 

4 . 3 Use of Special Forms with Spooled Devi ces 

Output files directed to spooled devices are queued and held 
until the spooled device becomes free. Because of this, a special 
procedure is required to synchronize the mounting of special forms 
wit 1 1 the printing of a file that requires the form. 

If the first character of the first line in a file directed 
to a spooled device is a right square bracket ("]"), TSX-Plus will 
interpret the following one to six characters in the file as the 
name of the form that must be mounted when the file is printed. 
Form names may be from one to six characters in length and must be 
specified immediately following the initial square bracket 
character. The form name must be terminated with a carriage 
return, line feed. Square bracket characters are not significant 
to TSX-Plus in other than the first character position of the 
f i 1 ei . 

If a spooled file does not begin with a right square bracket 
character, TSX-Plus uses the form name that was last specified by 
the user with a FORM command (Section 2.3.20). If no FORM 
command has been issued by the user, TSX-Plus uses the form name 
"STD" for the file. 

Each time TSX-Plus attempts to select a file to be printed on 
a spooled device, it first looks for a waiting file that requires 
the same form that is currently mounted on the spooled device. If 
several such files are available, the oldest one is selected and 
star- ted. If no file can be found that requires the currently 
mounted form, TSX-Plus selects the oldest file requiring a 
different form and issues a form mount request to the operator's 
terminal. The message appears as: 
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"Mount 'XXXXXX' form on ZZ" 

The ternlnal to which the message is directed is the one that was 
declared to be the operator's console when the TSX-Plus system was 
generated. 

Once the form mount request message is printed, the spooler 
for the device requiring the form mount is suspended. In order to 
restart the spooler the operator must enter a SPOOL-FORM or 
SPOOL-LOCK command. These commands tell the spooler that a 
particular form has been mounted and is ready for use. The 
operator does not have to mount the form that was called for in 
the form mount request message. He may mount any form he desires, 
in which case TSX-Plus will search for a file that needs the 
mounted form. 

The SPOOL-FORM and SPOOL-LOCK commands are both used by the 
operator to indicate which form has been mounted; however, there 
is a difference in the effect of the two commands. When TSX-Plus 
has processed all files that need the currently mounted form, it 
checks to see if there are files requiring a different form. If 
there are any, it checks to see if the current form was mounted 
using a SPOOL-FORM or SPOOL-LOCK command. If a SPOOL-FORM command 
was 'used, TSX-Plus issues a form mount request message. If a 
SPOOL-LOCK command was used, TSX-Plus considers the current form 
to be locked on the printer and does not issue a form mount 
message; rather, it waits for new files to be created that need 
the currently mounted form. 



4 . 4 Form Al i gnment Procedure 

When mounting a new form it is necessary to have a way to 
verify the correct positioning of the form before starting 
production printing on the form, 
this facility. 



The SPOOL-ALIGN command provides 
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form has been mounted. 
4) TSX-Plus begins printing the oldest file that needs the 
currently mounted form. 

The SPOOL-ALIGN command may be Issued at any time, but it is 
typically used between the time a form-mount message Is issued and 
the SPOOL-FORM or SPOOL-LOCK command is entered. 

4. 5 The SPOOL Command 

The SPOOL command is used to control the operation of the 
spooling system. The form of the SPOOL command is: 

. SPOOL device, function, para me ter 

where "device" is the name of a spooled device, "function" 
indicates the operation to be performed and "parameter" is an 
optional item of information used by some functions. Each of the 
avai'lable functions is described below. 

4. 5„ I The FORM and LOCK Functions. The FORM and LOCK functions are 
used to specify the name of the currently mounted form. The form 
name is specified in the "parameter" field of the command. The 
FORK function allows TSX-Plus to request a form mount when a 
different form is needed. The LOCK function specifies that the 
form is to be locked on the printer and form mount request 
messages are not to be generated. See Section 4.3 for further 
information. 



Examples : 



.SPOOL LP , FORM, BILLS 
.SPOOL LP, LOCK, BILLS 
.SPOOL LP,FORM,STD 



Note the difference between the FORM command (Section 2.3.20) 
and the SPOOL command with the FORM or LOCK functions. The FORM 
command is used by the TSX-Plus user to specify the default form 
name to be used with subsequently generated spool files. The 
SPOOL FORM/LOCK commands are used by the TSX-Pl us opera t or to tell 
the spooling system which form is currently mounted. 

4 . 5 . . 2 The ALIGN Function. The ALIGN function is used to cause a 
form al ignment file to be printed on a spooled device. The name 
of the file to be printed is specified in the "parameter" field of 
the command. The default file extension for form alignment files 
is "AL:J". See Section 4.4 for f ur t he r i nf orma 1 1 on . 

Examples: 



. SPOOL 
. SPOOL 
. SPOOL 



LP , ALIGN, BILLS 

LP, ALIGN, RKl :P AYROL.DAT 

LP, ALIGN, DX:RP0RT2 
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4.5. 3 The DEL Function. The DEL function causes the file currently 
being printed on the Indicated spooled device to be deleted. The 
DEL function has no effect If no file Is currently being printed. 



Exanp les : 



.SPOOL 
. SPOOL 



LP, DEL 
LX,DEL 



A. 5.4 The SKIP Function. The SKIP function causes the spooler to 
skip~over the next n blocks in the spool file that is currently 
being printed, where n is specified in the parameter field of the 
instruction. Each block in the spool file contains 508 
characters. Printing of the file continues after the indicated 
number of blocks have been skipped. 



Examples: 



. SPOOL 
. SPOOL 



LP, SKIP, 10 
LP, SKIP, 100 



4.5.5 The BACK Function. The BACK function causes the spooler to 
skip~backward in the spool file a number of blocks and then resume 
printing at that point. The number of blocks Involved is 
specified when TSX-Plus is generated. 



Thi s 



f unc 1 1 on is 
particularly useful for recovering from paper tears or remounts. 
The spooler will finish printing the current block before doing 
the backup . 



Exanp les : 



. SPOOL 
. SPOOL 



LP, BACK 
LX, BACK 



4.5.6 The STAT Function. The STAT function Is used to determine 
the "staTus of a spooled device. Information returned includes the 
condition of the sp oo le r--ac t 1 ve , idle, waiting for a form mount; 
the name of the currently mounted form; and information about 
files waiting to be printed on the device. The SHOW QUEUE command 
may also be used to display Information about files in the spooler 
queue. 

Examples: 

.SPOOL LP, STAT 
. SPOOL LX, STAT 

^•^•^ Tbe SING and MULT Functions. The SING and MULT functions 
con t^o 1 how the spooler will handle multiple files queued for the 
sane form. In "MULT" mode (the initial setting) 
request message is generated if a spool file is 



the currently 
a ut oma 1 1 cal 1 y . 



mounted form. 



Processin; 



of 



no form mount 

found that needs 

the file begins 
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In "SIfIG" node a form nount request Is generated for every 
file even If the file needs the currently mounted form. This is 
useful where equipment setup or form alignment is needed for every 
file. 

Examples: 



. SPOOL 
. SPOOL 



LP, SING 
LP, MULT 



4» 5. 8 The HOLD and NOHOLD Func t ions . A spooled device that is in 
the HOLD mode will not begin to process a spool file until the 
file Is completely created and the I/O channel associated with the 
file is closed. A spooled device that is in UOHOLD node will 
begin to process a spool file as the file is being created. 

In MO HOLD mode, the spooler will begin to process a file 
sooner; however, if the file is being created slowly, the spooled 
device will remain busy (and unavailable to other users) for as 
long as it takes to finish generating the file. If the spool 
storage file is completely filled, the spooler will attempt to 
free space by beginning to process open spool files even if HOLD 
is in effect. 

The default HOLD/NOHOLD mode is established when the TSX-Plus 
system is generated. A HOLD/NOHOLD command remains in effect 
until another HOLD/NOHOLD command is issued or the system is 
restar'ted. 

Examp 1 es : 



.SPOOL LP, NOHOLD 
.SPOOL LP, HOLD 
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5 « Program Cont rol l e r Ternl nal Op t Ions 
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Plus provides a facility whereby a running program can 
ly alter some parameter settings relating to the user's 
ng line. This facility is invoked by having the running 
utput a special lead-in character followed by one or more 
characters. The lead-in cliaracter alerts TSX-Plus to the 
the following one or two characters are not to be sent 
user's terminal, but rather are to be interpreted as a 
o TSX-Plus. The character that is to be used as the 
haracter may be specified when TSX-Plus is generated; its 
lue is" octal 35(decimal 29, CTRL-SHI FT-M ) . The character 
ediately follows the lead-in character specifies the 
to be performed. The available functions are listed 



function 
character 

A 
B 
C 
D 
E 
F 
H 
I 
J 
K 
L 
H 
N 

P 

Q 

R 
S ^ 

T 
U 
V 



meani ng 

Set rubout filler character. 

Enable VT52 & VTIOO escape-letter activation. 

Disable VT52 & VTIOO escape-letter activation 

Define new activation character. 

Turn on cliaracter echoing. 

Turn off character echoing. 

Disable virtual lines. 

Enable lower case input. 

Disable lower case input. 

Enable deferred character echo mode. 

Disable deferred character echo mode. 

Set transparency node for output. 

Suspend command file input. 

Restart command file input. 

Reset activation character. 

Set activation on field width. 

Turn on high-efficiency TTY mode. 

Turn on single-character activation mode. 

Turn off single -character activation mode. 

Enable non-wait TT input test. 

Set field width limit. 



These functions have a temporary effect in that tliey are 
automatically reset to their normal values when a program exits to 
KMON. They are not reset If a .CHAIN is performed. 
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5.1 "A"-f unct lon-"Se t rubout filler character 
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5 . 2 "B" and "C" f unc 1 1 ons--Se t VT52 _& VTIOO escape-letter activation 

VT50 and VT52 terminals are equipped with a set of special 
function keys marked with arrows and other symbols. When 
pressed they transmit escape (octal 33) followed by a letter. 
The "B" function tells TSX-Plus to consider escape-letter to 
be an activation sequence. The escape character and the 
letter are not echoed to the terminal, but are passed to the 
user. The "C" function disables this processing and causes 
escape to be treated as a normal character (Initial setting). 

5.3 "D" - functlon--Define new act 1 vat ion character 

Under normal circumstances TSX-Plus only schedules a job for 
execution and passes it a line of input when an "activation" 
character such as carriage return is received. The "D" 
function provides the user with the ability to define a set 
of activation characters that are used in addition to 
carriage return. 

To define a new activation character the running program 
sends to TSX-Plus a lead-in character followed by the letter 
D, followed by the new activation character. The maximum 
number of activation characters that a program may define 
specified when the TSX-Plus system is generated. 



Is 



as 



an 



Using this technique, any character may be defined 
activation character, including such characters as letters, 
rubout, CTRL-U, and CTRL-C. When a user defined activation 
character is received, it is not echoed but Is placed in the 
user's Input buffer which is then passed to the running 
program. 

By specifying CTRL-C as an activation character, a program 
may lock itself to a terminal in such a fashion that the user 
may not break out of the program in an uncontrolled manner. 
If carriage return is specified as a user activation 
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character, neither It nor a following line feed will be 
echoed to the terminal. TSX-Plus will also not add a line 
feed to the Input passed to the program. 

5.4 "E" and "F" functions-- Control character echoing. The "E" and 
- "F" f unct 1 ons are used to turn on and off character echoing. 

The "E" function turns It on, and the "F" function turns It 
off. An example of a possible use Is to turn off echoing 
momentarily while a password Is being entered. 

5.5 "II" function — Disable virtual line use. The "H" function 
■ disables the virtual line facility for the timesharing line. 

5.6 "I" and "J" functions — Control lower case Input. The "I" 

function sets TSX-Plus to allow lower case characters to be 

passed to the running program. The "J" function causes 

TSX-Plus to translate lower case letters to upper case 
letters. 



5.7 



5.8 



5.9 



"K" and "L" functions-- Control character echoing. The "K" 
function causes TSX-Plus to enter "deferred" character echo 
mode. The "L" function causes TSX-Plus to enter immediate 
character echo mode. See description of the DEFER option of 
the SET command for an explanation of deferred echo mode. 




recognize the leading character (octal 35) 

program control function follows. The only way to turn off 
transparency mode is to exit to KMON. 

"N" and "0" Functions-- Control input from command files . When 
a command file is being used to run programs (see Chapter 9), 
all input which would normally come from the user's terminal 
is instead drawn from the command file. Occasionally, it is 
desirable to allow a program running from a command file to 
accept input from the user's terminal rather than the command 
file. The "N" function suspends input from the command file 
so that subsequent input operations will be diverted to the 
terminal. The "0" function redirects input to the command 
file. These functions are Ignored by TSX-Plus if the program 
is not being run from a command file. See also the 
description of the PAUSE keyboard command which can also be 
used to control command files. 



5.10 "P"- function — Reset activation character. The "P" function 
performs the complement operation to the "D" function. The 
"P" function is used to remove an activation character that 
was previously defined by the "D" function. To reset an 
activation character the running program sends to TSX-Plus a 
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lead-in character followed by the letter "P" followed by the 
character that is to be removed from the activation list. 
Only activation characters that were previously defined by 
the "D" function may be removed by 



the "P" function. 
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5.12 "R"-functlon — Turn 



on. high-efficiency 

function causes TSX-Plus to place the 
efficiency" tty mode. The effect of this is 



TTY mode. 



The "R" 

line in "high 
to disable most 
of the character testing overhead that is done by TSX-Plus as 
characters are transmitted and received by the line. Once a 
program has entered high-efficiency mode characters sent to 
the terminal are processed with minimum system overhead: tab 
characters are not expanded to spaces and form-feed 
characters are not treated specially. Also, TSX-Plus does 
not check to see if the character being sent is the TSX-Plus 
terminal control "leadin" character. This means that no 
further program controlled terminal commands may be Issued 
until the program exits. Characters received from the 
terminal are passed to the program with minimum processing: 
they are not echoed, and control characters such as rubout, 
control-U, control-C, control-W and carriage-return are all 
treated as ordinary characters and passed directly to the 
program. Before entering high-efficiency mode the program 
must declare a user defined activation character that will 
signal the end of an input record. High-efficiency mode of 
TTY I/O is designed to facility machi ne- t o-machine 
communication; it is also useful for dealing with buffered 
terminals that transmit a page of information at a time. 

5.13 "S"-f unction--Turn on s ingle-character activation mode. The 
"S" function causes TSX-Plus to allow a program to do 
single-character activation by setting bit 12 in the Job 
Status V/ord. Normally TSX-Plus stores characters received 
from the terminal and only activates the program and passes 
the characters to it when an activation character such as 
carriage-return is received. It does this even if bit 12 in 
the Job Status Word is set^ which under RT-11 causes the 
program to be passed characters one-by-one as they are 
received from the terminal. The 



"S" function can be used to 
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cause TSX-Plus to honor bit 12 In the Job Status Word. If 
bit 12 Is set and the program is single-character activation 
mode, TSX-Plus passes characters one-by-one to the program as 
they are received and does not echo the characters to the 
terminal. The /SINGLECHAR switch for the RUN command can 
also be used to do this. 

5.14 "T"-function--Turn off single-character activation mode. The 
"T" function is the complement of the "S" function. It turns 
off single-character activation mode. 



5.15 "U"-f unction--Enable non-wait 
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6. TSX-Plus EriT'S 



The following EMT service calls are available to jobs running 
under TSX-Plus. 

6 . 1 D( aternlnlng ij_ a^ job 1 s running unde r TSX-Plus » The proper way 
to deternine if a job Is running under TSX-Plus Is to do a .SERR 
EMT (to suppress error aborts) and then to do the EHT to determine 
the TSX-Plus line nun her (see below). If the job Is running under 
TSX-Plus the EMT will return without error; if not under TSX-Plus 
the carry bit (Indicating an error) will be set on completion of 
the EMT. 



6.2 Determining the TSX-P lus line number . The following EMT will 
return in RO tlie number of the line to which the job is attached. 
Real lines are numbered consecutively starting at 1 in the same 
order they are specified when TSX-Plus is generated. Detached job 
lines occur next and virtual lines are numbered last. 

The form of the EMT is: 



EMT 37 5 
with FIO pointing to the following argument area 
.BYTE 0,110 



6 . 3 Determining the TSX-Plus 1 1 cense number. The following EMT 
will return in RO as a 16-bit binary value the license number of 

the TSX-Plus system. The form of the EMT is: 

EMT 37 5 
with RO pointing to the following argument block: 

.BYTE 0,124 
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6 . 4 Deterninlng t he t e rml nal type. The following EMT will return 
In RO a value that Indicates what type of time-sharing terminal is 
being used with the line. The form of the EMT is: 

EMT 37 5 

with RO pointing to the following argument block: 

.BYTE 0.137 



The terminal type is specified either when the TSX-Plus system is 
generated or by use of the SET TT command (e.g., SET TT VTIOO). 
The currently returned terminal type 



codes are listed below. 





Termlnal-t 


yp 


e 


C 


ode 




(Unknown) 













V T 1 (D 








2 




Ha z e 1 1 i ne 








3 




ADM3A 








4 




LA36 








3 




L A 1 2 








6 




Diablo 








7 




Q unc 








8 


A type code 


of ( zero ) 




is 


re 


turned 


unknown. 













if the terminal type is 



6 . 5 Se nding a_ message t o another line. The following EMT can be 
used to cause a message to display on another line's terminal. 
The form of the emt is: 

EMT 375 

with RO pointing to the following argument block: 

. BYTE 0,127 

•WORD Line -number 

.WORD Message-address 

where " 1 i ne-n umbo r " is the number of the line to which the message 
is to be sent and "message-address" is the address of the start of 
the message text that must be in ASCIZ form. 
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6 . 6 riount £ file structure. This EMT Is used Co tell TSX-Plus that 
a file: structure is being mounted and that TSX-Plus should begin 
do inn; file directory caching for the device. The effect of this 
EMT is the sane as doing a aystein MOUNT keyboard command. The 
f o r in o f the EMT is: 



EMT 



375 



vvTitli RO pointing to the following argument block: 

.BYTE 0,134 

. Iv R. D L) e V i c e - s p e c - a d d r e s s 

.WORD 

where "device-spec-address" is the address of a word containing 
the RAD 50 form of the name of the device on which the file 
structure is being mounted. If there is no room left in the table 
of mounted devices, the carry bit is set on return and the error 
code returned is 1. 



6 . 7 Dismounting a_ file struct ure » This emt can be used to tell 
TSX-Plus to stop doing file directory caching for a file structure 
mounted on a particular drive. The effect of this emt is the same 
as doing a DISMOUNT keyboard command. The form of the emt is: 

EMT 375 

with RO pointing to an argument block of the following form: 

. BYTE 0,135 

.WORD Device-spec-address 

.WORD 

where "device-spec-address" is the address of a word containg the 
RAD50 value of the name of the device on which the file structure 
is mounted. 



6 . 8 Se t T e r m i n a 1 Read Time-out Value . This emt can be used to 
specify a time-out value that is to be applied to the next 
terminal input operation. This emt allows you to specify the 
maximum time that will be allowed to pass between the time that 
you issue a command to get input from the terminal (.TTYIN) and 
the time that an activation character is received to terminate the 
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emt a special 



activation 
the 



input field. You also specify with this 

character that i<^ rf^turned as the terninatino; character for 
field if the i -". n 1 1 1 n o r i t i n t i -; o s out without receiving 
activation r h a r i o t '■> r f r o p, tliP ternlnal. The form of the emt 



an 
Is: 



V 



17 D 



with RO pointing; to the following argument block: 



. BYT?: 
.Iv'ORD 
.WORD 



0,117 

1 1 n c - V a 1 u e 

a c t i V a t i o n - c h a r a c t e r 



where "tine-value" is tiie tine-out value specified in 0.5 second 
units and "activation-character" is a single character value that 
is to be returned as the last character of the field if a time-out 
occurs ^. The tine value specified with this emt only applies to 
the next lerninal input field. The tine value is reset when the 
next field is received fron the terninal or the time-out occurs. 
A new tine-out value nust be specified for each input field that 
is to be tine controlled. 



6 . 9 Estiabllshing Break Se n t i na 1 C ontrol. 

The following EMT can be used to declare a completion routine 
that will be tri^.zeered when the "Break" key is pressed. The form 
of the EMT i s 



EM' 



375 



with RO pointing to the following argument block: 





. BYTE 




0,133 










.WORD 




. b r k c h r 










.WORD 
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character that is declared 
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nted, specify the value 

and only the real "BREAK" 

n some systems the console 

hardware GOT module and 

s TSX-Plus function. Only 

time for each user. If a 
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routine is declared. If an address of (zero) is specified as 

the address of the completion routine (.cplrtn), any previously 

specified break routine is cancelled and the break key connection 

is cancelled. A break routine can be used to signal an 



asynchronous request for service to 



running program. 



2ood 



example of its use 
debugging program. 



would be to trigger entry to an interactive 



6.10 Checking for Terminal Input Errors 

The following EMT can be used to determine if any terminal 
input errors have occured. The form of the erat is 

EMT 37 5 

with RO pointing to the following argument block: 



. BYTE 



0,116 



On return from the emt , the carry-flag is set if an input error 
has occured since the line logged on or since the last time a 
check was made for input errors. The two types of errors that are 
monitored by this emt are hardware reported errors (parity, 
silo-overflow, etc.) and characters lost due to TSX-Plus input 
buffer overflow. 



6.11 Checking for Ac ti vat ion Cha r acters 

The following emt can be used to determine if any activation 
characters have been received by the line but not yet accepted by 
the program. The form of the EMT is 

EMT 37 5 

with RO pointing to the following argument block: 

•BYTE 0,123 

If there are pending activation characters, the carry-flag Is set 
on return from the emt; otlicrwise the carry-flag is cleared. 
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6 » 1 2 Sendi ng a_ Block o f Characters t o the Te rml na 1 

The following ent can be used to efficiently send a block of 
characters to the terminal. The form of the ent is 

EMT 375 

with RO pointing to the following argument block 



BYTE 
WORD 
WORD 



0,114 

.buffer 

.count 



Where ".buffer" is the address of the buffer containing the 
characters to be sent and ".count" is a count of the number of 
characters to be sent. This emt is much more efficient to use 
than a series of .TTYOQT emt ' s -- it has the same efficiency as a 
.PRINT ent but it uses a count of the number of characters to send 
rather than having the character string in ASCIZ form. 



6.13 Accepting a Block of Characters From the Term! nal 



The following emt can 
the terminal input buffer up 
character entered. The form of 



be used to accept all characters from 
to and including the last activation 



the ent i s 



EMT 27 5 
with RO pointing to the following argument block 



BYTE 
WORD 
WORD 



0,115 

.buffer 

.size 



w h e r es 
are to 
b y t e £1 ) 
c h a r a c 
to an 
c o n t a 1 
specif 
emt i s 
ent ' s ; 
page b 



".buffer" is the address of the buffer where the characters 

be stored and ".size" is the size of the buffer (number of 

This emt causes a program wait until an activation 

ter is entered and then returns all characters received up 

d Including the last activation character. On return RO 

ns a count of the number of characters received. If the 

led buffer overflows, the carry-flag is set on return. This 

substantially more efficient than doing a series of .TTYIH 

it is particularly well suited for accepting input from 

uffered terminals. 
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6 . 1 A Turni ng High-efficiency Terminal Mode On and Off 
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cat e wi th 
t o cont r ol 



with RO pointing to the following argument block: 
.BYTE .code ,120 

where ".code" is 1 to turn high-efficiency mode on and to turn 

i t o f f . 



6.15 De terming number of free b locks in spool file 

The following EMT will return in RO the number of free blocks 
in the spool file. The form of the EMT is: 

E!1T 375 

with RO pointing to the following argument area: 

.BYTE 0,107 
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6.16 Set /Reset OPT activation mode 

The following EMT can be used to set TSX-Plus to activate on 
characters that are appropriate to ODT. In this mode TSX-Plus 
considers all characters to be activation characters except 
digits, ',', '$', and ';'. The form of the EIIT Is: 

EMT 37 5 
with RO pointing to the following argument area: 
..BYTE .code, ill 

where .code Is 1 (one) to turn on ODT activation mode and (zero) 
to reset to normal mode. 
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SHARED FILE RECORD LOCKING 



TSX-Plus provides;! record locking facility that is useful In 
sit II at: ions where programs lieing run fron several terminals wish to 
update a connon data file. Through the record locking facility a 
program may gain exclusive access to one or more blocks in a file 
by locking those blocks. Other users attempting to lock the sane 
blocks will be denied access until the first user releases the 
locked blocks. 

The usual protocol for updating a shared file being accessed 
bv several users is as follows. 



Op en file. 

Tell TSX-Plus that file 

Lock all blocks in file 

Read locked blocks into 

Make update to record. 

Write updated blocks to 

UnlocV: blocks. 

P\.epeat steps 3-7 as needed. 

Closefile. 



is "shared". 

which contain desired record. 

core. 

file. 



DIBQL record locking p r ocedure s 

See Appendix A for information on performing record locking 
frotnDIBOLprograns. 

A s s e n b 1 y language record 1 ocking E M T ' s 

At the assembly language level TSX-Plus provides 4 EMT's to 
control record locking. 



7 . 1 Op cni ng a_ shared file 

Before a file can be used with shared access it must be 
opened by using a standard ..LOOKUP ent . After the lookup has 
completed successfully the following emt may be used to declare 
the file to be opened for shared access. The form of this emt is: 

EMT 37 5 

with RO pointing to the following argument area: 

.BYTE .Chan, 125 
.WORD .access -code 

where .chan is the number of an I/O channel that has previously 
been opened to the desired file and .access-code is a value that 
indicates the type of access protection desired for the file. 
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The following access codes are recognized: 
Code Protection Access 
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When this emt is executed, TSX-Plus checks your specified 
protection mode and access type with that previously declared for 
the file by other users. If an access conflict arises because of 
your specified access characteristics an error code of 4 is 
returned for the emt. If no access conflict is detected, your 
specified access code is saved with the file and will be used to 
check for conflicts with future access requests issued by other 
users. 

It is possible to have several channels simultaneously open 

to different shared files. The exact number of channels that can 

be open to shared files and the total number of shared files that 

may be opened are specified when the TSX-Plus system is generated. 



Once all access to the file is completed, 
should be closed using the standard .CLOSE or 
below for information about saving the status of 
has been opened to a shared file. 



the I/O channel 

PURGE emt's. See 

a channe 1 that 



The error codes that can be returned by this emt are listed below: 



errors : 



code 
1 
2 
3 

4 



mea ni ng 

Channel has not been opened to a file. 

Too many channels opened to shared files 

Too many shared files open. 

File protection-access conflict 
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7 « 2 Saving the Stat us of a. Shared Fl le Channel 

A standard .SAVESTATUS emt may be used to save the status of 
a shared file channel. If this Is done, all blocks that are being 
held locked In the file remain locked until the channel Is 
reopened and an unlock emt (see below) Is done. 

When using a single channel number to access several shared 
files it Is convenient to Initially do a .LOOKUP on each file then 
declare the file to be shared (emt above) and then do a 
.SAVESTATUS. The channel being used to access the set of files 
can then be switched from one file to another by doing a .PURGE 
followed by a .REOPEN. However, before doing the .PURGE, TSX-Plus 
must be told that you wish to save the shared-file status of the 
file (otherwise all locked blocks will be unlocked and the file 
will be removed from the shared-file list). The form of the emt 
used to perform this function is 

EMT 375 

with RO pointing to the following argument block: 



.BYTE 



c h a n , 12 2 



where .chan is the I/O channel number. The effect of this emt is 
to suspend the connection between the shared file information 
table and the I/O channel. Any blocks that are currently locked 
in the file remain locked until the channel is reopened to the 
file (by using a standard .REOPEN emt). After doing this emt the 
channel may be freed by using a .PURGE emt. 



7 . 3 Wai t ing for £ Locked Block 



The following emt 
file. If the requested 
requesting user's job 
becomes available. The 



can be used to lock a specific block in a 
block is locked by another job, the 
will be suspended until the desired block 
form of the emt is 



EMT 37 5 



with RO pointing to the following area: 



. BYTE 
.WORD 



. chan ,102 
.block 



where .chan is the number of an I/O channel that has previously 
been declared to be open to a shared file; .block is the number of 
the block in the file to be locked. Other blocks in the file 
which were previously locked remain locked. The maximum number of 



-5 5- 



blocks which nay be simultaneously held locked Is specified when 
TSX-Plus is generated. A block number of -1 (octal 177777) can be 
used to request Chat all blocks in the file be locked. If several 
users request the same block, access will be granted sequentially 
in the order that the requests are received. 



errors : 



code 

1 
2 



meanl ng 

Channel is not open to a shared file 
Request to lock too many blocks in file 



7.4 T r y i n g to Lock A Block 



This emt is similar in operation to the previous emt . It too is 
used to request that file blocks be locked. The difference is 
that if the requested block is already locked by another user the 
previous EMT suspends the requesting program whereas this EMT does 
not suspend the program but rather returns an error code. If the 
block is available it is locked for the requesting user and no 
error is reported. The form of this EMT is: 

EMT 37 5 



w 



ith RO pointing to the following argument area: 



.BYTE 
.WORD 



. chan ,103 
. block 



errors: 



code 

1 
2 
3 



meani ng 

Channel is not open to a shared file. 
Request to lock too many blocks in file. 
Requested block is locked by another user 



Z^^ U nlocking A Specific Block 

This emt is used to unlock a specific block in a file 
form of the emt is 



The 
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EMT 375 

with RO pointing to the following argument block: 

. BYTE .Chan, 1 13 
.WORD .block-number 

where ".chan" is the number of the I/O channel opened to the 
shared file and ".block-number" is the number of the block to be 
unlocked . 

e rrors: code meaning 

~ 1 Specified channel not opened to a shared file 



7 . 6 Unlocking All Locked Blocks In A Fi le 

This emt is used to unlock all blocks held locked for a file. 
The form of the emt is 

EMT 375 

with RO pointing to the following argument area: 

.BYTE .Chan, 101 

where .chan is an I/O channel number that is open to a shared 
file.. When this EMT is executed all blocks previously locked by 
the user on the shared file are unlocked. Blocks locked by the 
user on other files are not released nor are blocks of the same 
file that are locked by other users. 



error: code 



meani ng 

Channel is not open to a shared file. 



7 . 7 Checking For Writes To A Shared Fi le 

The following emt can be used to determine if any other user 
has written to a shared file. The form of the emt is 
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EMT 37 5 
with RO pointing to the following argument block 



. BYTE 



. chan ,121 



where ".chan" is the I/O channel number opened to the shared file. 
If no other user has written to the file since the file was opened 
by tlie user issuing this ent or since that last tine this emt was 
issued for the file, the carry-flag is cleared on return from the 
ent. If the file has been written to by some other user since the 
last check was made, the carry-flag is set on return and an error 
code of 2 is returned. 

This ent can be used to advantage in a situation where data 
from some block in the file is being held in a buffer and it is 
desired to determine if the data is valid or if it may be invalid 
because some other user night have altered it by writing to the 
file. The usual sequence of operations in this situation is to 
first lock the block whose data is in the in-nenory buffer, then 
do the ent to see if the file has been written to; if the file has 
not been modified the data in nenory is valid and can be used, 
otherwise the block nust be reread fron the file. 
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8. MESSAGE COMMUNICATIONS FACILITIES 



provides an optional facility that allows running 

send messa,^,es to each other. This message 

facility allows programs to send messages through 

named channels, check to see If messages are pending, and suspend 
execution until a message is received. 



TSX-Plus 
programs to 
communi cation 



8 . 1 Message Channel s 

Messages are trans 
TSX-Plus "Message Channel 
from a sending program, 
with the channel and deli 
that requests a messag 
totally separate from I/O 

Each active messag 
six character name that i 
programs to identify t 
channels is defined wh 
associated with the ch 
running programs. A mess 
messages are being held 
or if any program is wait 
message channels become 
and may be reused by anot 

Once a message is 
remain in the queue until 
system is restarted. A 
does not remove any pendi 
one program to leave a 
later. 



ferred to and from programs by using 
s". A message channel accepts a message 
stores the messsage in a queue associated 
vers the message to a receiving program 
e from the channel. Message channels are 
channe 1 s . 

e channel has associated with it a one to 
s used by the sending and the receiving 
he channel. The total number of message 
en TSX-Plus is generated. The names 
annels are defined dynamically by the 
age channel is said to be "active" if any 
in the queue associated with the channel 
ing for a message from the channel. When 
inactive they are returned to a free pool 
her program. 

queued on a channel, that message will 

some program receives it or the TSX-Plus 

program's exiting to the keyboard monitor 

ng messages that it queued. This allows 

message for another program that will run 



. 2 1 3 e n d 1 n g a_ Message 



An 
use to 
already 
end of 
cont inue 
message 
of the E 
sending 
the EMT. 



EMT is provided for the assembly language programmer to 
queue a message on a named channel. If other messages are 
pending on the channel, the new message is added to the 

the list of waiting messages. The sending program 
s execution after the EMT and does not wait for the 

to be accepted by a receiving program. During processing 
MT the message is copied to an internal buffer, and the 

program is free to destroy its message on completion of 
The form of the EMT is: 
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EMT 37 5 
with RO pointing to the following argument area: 

.BYTE 0,104 

.WORD .chadr 

.WORD .nsadr 

.WORD .rasslz 

where .CHADR is the address of a six byte field containing the 

nane of the message channel in ASCII with trailing blanks if the 

name is less than six characters. .HSADR is the address of the 

beginning of the message text. .MSSIZ is the message length in 
bytes. 

errors code meani ng 

1 All message channels are busy. 
(Re-gen TSX~Plus and increase the 
value of the IIAXMC parameter.) 

2 Maximum allowed number of messages 
are being held in message queues. 
(Re-gen TSX-Plus and increase the value 
of the MAXMSG parameter . ) 

4 The transmitted message is too long. 

(Message is truncated to maximum 
length. ) 

Note that the maximum message length is defined during system 
generation by the MSCHRS parameter. If a message longer than this 
is sent, only the first part of the message will be delivered and 
error code 4 will be returned. 



, 3 Checking for Pending Messag es 



The second EMT is used to receive a message from a named 

channel if a message is pending on the channel. If no message is 

pending, an error code (3) is returned, and the program is allowed 

to continue execution. The form of the EMT is: 

EMT 37 5 
with RO pointing to the following argument area: 

•BYTE 0,105 

.WORD ,. chadr 

.WORD ,msadr 

.WORD .mssiz 
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where .CHADR points to a field with a six character channel name; 
.MS ADR points to the buffer to which the message is to be placed 
and .MSSIZ is the size of the message buffer (bytes). 

If a message is received, its length (bytes) is placed in RO 

on return from the EMT . If the received message is longer than 

the message buffer (.MSSIZ), only the first part of the message 
will be recei ved . 



errors 



code 


3 



meanl ng 

Mo error. A message was received 
No message was queued on the 
named channel . 
Message was longer than the 
receiving buffer. 



8 A Waiting for 



a_ Me s sage 



The third EMT is used to suspend execution of a program until 
a message becomes available on a named channel. The form of the 
EMT is: 

EMT 37 5 

with RO pointing to the following argument area: 



.BYTE 
.WORD 
.WORD 
.WORD 



0, 106 
. chadr 
. m s a d r 
. ms s i z 



where .CHADR points to a field with a six character channel name; 
.MS ADR points to the buffer where the message is to be placed; and 
.MSSIZ is the size of the message buffer (bytes). 

The length of the received message (bytes) is placed in RO on 
return from the EMT. 



errors 



code 


1 



meanl ng 

No error. A message was received. 
All message channels are busy. 
(Re-gen TSX-Plus and increase the 
value of the MAXMC parameter.) 
Message was longer than the 
receiving buffer. 
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9. COMMAND FILES 

The TSX-Plus command file facility is significantly moro 
powerful than that provided by standard RT-11. Parameter strings 
may be specified when a command file is started; the parameters 
are stored by TSX-Plus and inserted in the text of the command 
file at selected points as the command file is processed. Unlike 
RT-U command files, TSX-Plus command files allow program data as 
well as system commands to be placed in a command file. Under 
TSX-Plus it is possible to set up a command file so that any 
request for data from device "TT" comes from the command file. 
This allows EDIT and TECO commands to be placed in a command file. 

A command file is invoked by typing: 

^filename paraml param2 . « . param5 

where "filename" is the name of the command file and "paraml", 
"param2", etc are parameter string arguments to the command 
file. The default extension for a command file is ".COM". 

When the name of a command file does not conflict with a 
system command, the command file may be invoked by typing: 

filename paraml , param2 , .«. paramS 

that is, the Q-sign may be left out. There are two differences 
between starting a command file with and without the Q-sign. With 
the (^-sign the default device searched for the command file is 
"DK". Without the 0-sign the default device is "SY". With the 
0-slgn the command file listing is initially set according to the 
last executed SET TT QUIET or SET TT NOQUIET command. Without the 
@-sign the command file listing is initially suppressed but may be 
turned on by putting a listing control command in the file. 

Parameter strings are normally delimited by spaces. Thus in 
the command: 

0TSTRUN ABC 123.45 2/3 

the string "ABC" is parameter 1, "123.45" is parameter 2 and "2/3" 
Is parameter 3. It some cases it may be desirable to Include 
spaces as part of a parameter string. If this is to be done, the 
first parameter must begin with the character "\" (left leaning 
slash), and the left-slash must be used as the parameter delimiter 
rather than spaces. For example, In the command line: 

0TSTRUN \A STRING\OF PEARLS 
parameter 1 is "A STRING" and parameter 2 is "OF PEARLS". 

Up to five parameter strings may be specified when the 
command file is started. The total number of characters in the 
parameter string may not exceed 60. 



-62- 



To Insert a parameter string In a command file put au 
up-arrow ("*") character followed by a digit In the range of 1 to 
5 at the desired point of insertion. The digit indicates which 
parameter string is to be inserted at that point. The 
up-arrow-digit sequence is replaced by the appropriate parameter 
string as the command file is being executed. If a parameter 
string is called for that was not specified when the command file 
was invoked, the up-arrow-digit will be deleted and no characters 
will be Inserted in their place. For example, consider the 
folio v;lng CO mm and file: 

R "1 
"3 = ^2 

If it is executed by use of the following command: 

(STEST FORTRAN PROG 

The result will be: 

R FORTRAN 
= PROG 



Command files may be nested, that is 
call another command file. When such a call 
strings for the outer level (calling) comman 
stack in TSX-Plus and then the parameter str 
command file are set up. When the called 
the parameters for the calling command files 
maximum depth of nesting Is governed by the 
string stack and the length of the actual p 
nesting depth of 3 can be reached even wl 
strings. If no parameters are specified, th 
toabout71evels. 



, one command file may 

occurs, the parameter 

d file are stored on a 

Ings for the called 

command file finishes, 

are restored. The 

size of the parameter 

arameter strings. A 

th very long parameter 

e nesting depth may go 



The command file listing status (SET TT QUIET) is also 
stacked as command files are nested. This means that an inner 
nested command file may have its listing turned on or off; when it 



exits the listing control will be reset to 
when the command file was called. This is 
outer-most command file, however, so if the 
file contains a SET TT QUIET command, it will 
effect;. 



the state it was in 

not done for the 

outer level command 

have a permanent 



Several combinations of characters take on special meaning 
when they are found within a command file. The up-arrow character 
(""") followed by a letter is replaced by the control character 
corresponding to the letter specified. Thus '"^c" becomes 
control-C. The escape character (alt mode) may be represented by 
up-arrow, dollar sign (""$"). 

Several combinations of characters within a command file 
perform special functions when they are encountered. These 
control character functions are carried out immediately by 
TSX-Plus as the characters are found. These control characters 
are not passed to the program. 
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control character function 



^( 



--) 



Stop listing command file. 
SET TT QUIET, except It 
command file. 



This has the same effect as 
only applies to the current 



Start listing command file. This has the same effect as 
SET TT NOQUIET except that it only applies to the 
current command file. 

Suppresses all TT output. Both the command file listing 
and any program output to TT are suppressed. The ""(" 
and "")" commands restart program generated output. 



Accept 
command 
do .GTL 
RT-11 ha 
as .TTYI 
t erml nal 
r eques t s 
command 
allows 
command 
to be 
a f f ec t s 
the "'^>" 



all TT 
file dat 
IN, .CS 
ndles al 
N or .RE 
The 
for d 
file reg 
data fo 
file. I 
placed 
Input re 
sequenc 



Input 

a 1 s on 

ISPC o 

1 comma 

AD bypa 
II '» V II 

a t a f r 
ardless 
r app 11 
t also 
In a 
que s t s 
e . 



from the command file. Initially 
ly passed to programs when they 
r .CSIGEN EMT's. This is the way 
nd files. Requests for data such 
ss the command file and go to the 
command causes all subsequent 
om the terminal to come from the 
of which EMT is used. This 
cation programs to be placed in a 
allows commands for TECO and EDIT 
command file. This command only 
that occur after TSX-Plus reads 



Return to standard data mode. The following command 
file data will only be passed to programs which do 
.GTLIN, .CSISPC or .CSIGEN EMT's (standard RT-11 mode). 



A PAUSE command is provided to 
command file to be suspended while the 
manual operation. 



allow the execution of a 
operator performs some 



The form of the PAUSE command is: 



PAUSE comments 

where "comments" may be any string of characters. When a PAUSE 
command is encountered within a command file, the PAUSE command is 
printed on the terminal followed by ">>". Execution of the 
command file is then suspended until carriage return is pressed. 
See also the description of the "N" and "0" program controlled 
terminal options that affect command file input. 
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A DISPLAY command may be placed In a command file to cau^e <i 
line of text to be displayed at the terminal when the DISPLAY 
command is executed. The form of the DISPLAY command is: 

DISPLAY comments 

where "comments" may be any line of text to be printed at the 
terminal. This is useful when running command files in "quiet" 
mode so that they are not being listed. 
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10. TSX-Plus Performance Monitor Feature 



TSX-Plus includes a performance analysis facility that can be 
used to monitor the execution of a program and determine what 
percentage of the run time is spent at various locations within 
the program. \Jhen the performance analysis facility is being used 
TSX-Plus examines the program being monitored when each clock tick 
occurs (50 or 60 times per second) and notes at what location in 
the program execution is taking place. Once the analysis is 
completed the TSX-Plus performance reporting program (TSXPM) can 
be used to produce a histogram showing the percentage of time 
spent at various locations during the monitored run. 

There are three steps involved in performing a performance 
analysis on a program: 

1) Use the MONITOR command to begin the analysis. 

2) Run the program to be monitored. 

3) Run the TSXPM program to print a histogram of the result. 

10.1 S tarting a_ Performance Analy si s 

The first step in doing a performance analysis is to use the 
MONITOR keyboard command to tell TSX-Plus that a performance 
analysis is to be done on the program that will be run next. The 
form of the MONITOR command is 

MONITOR base-address, top-address [ , cell-size] /switches 
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Examp le s : 

MONITOR 1000, 13000/1 

MONITOR 20000,40000,10 

MONITOR 2000,6000 

The effect of the MONITOR command is to set up parameters 
within TSX-Plus which will be used to monitor the next program run 
It does not actually begin the analysis so there is no rush in 
running the program to be monitored. 
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Only one user may be doing a performance analysis at a time. 
This Is because the performance analysis histogram buffer Is a 
common memory area that may not be In use by more than one user at 
a time. An analysis is In effect for a user between the time the 
MONITOR command is Issued and the TSXPM program is run to display 
the results of the analysis. Running the TSXPM program terminates 
the performance analysis and billows other users to perform 
analyses. Note also that space for the performance analysis data 
buffer must be reserved when TSX-Plus is generated. 



Once the MONITOR command has been Issued 
monitored is run by using the standard "RUN 
link nap of the program should be availabl 
addresses inthe program that are appropriat 
program is overlayed and the region to be m 
overlay area, the analysis technique is 
necessary to use the performance monitor emt ' 
to control when the analysis is turned on 
particular overlay segment running in the reg 
If a program being monitored does a .CHAIN to 
analysis continues and the times reported wil 
the programs run. 
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1 . 2 D 1 splaying The Re s ul t s f The Analys i s 
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After receiving the file specification TSXPM prompts for a 
title line. Enter a line of text which will be printed as a page 
title in the histogram file. Press return if you wish no title. 

The next item of Information requested by TSXPM is a set of 
base offset values. The base offset values are optional. Base 
offsets are useful in the situation where you have several modules 
making up a program being monitored and you want the addresses 
displayed on the performance analysis histogram to be relative to 
the base of each module. You may specify up to 10 offset values. 
Each offset value is specified as an offset module number (in the 
range to 9) followed by a comma and the base address of the 
module (see example below). If offset values are specified, TSXPM 
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determines In which nodule each cell of the histogram falls and 
displays the address as a module number and offset within the 
module. After you enter all desired module offsets, enter return 
wl thout a val ue . 

After the base offset values are entered the histogram will be 
produced and written to the specified device and file. After the 
histogram is generated TSXPH prints the asterisk prompt again at 
which point you may enter the name of another device/file and 
produce the histogram again if desired or you may type control-C 
to return to the keyboard monitor. 

Example use of TSXPIl 

.R TSXPM 

* LP: /H; 5 

Ti. tie: PERFORMANCE ANALYSIS 0_F EIGENVALUE CALCULATION 

Base offsets: 

> 1, 1000 

> 2,2134 

>" 3 , 5 2 1 2 

>' 

[Histogram is produced at this point] 

* control-C 

The histogram produced by TSXPM consists of one line per 

histogram cell. Each line contains the following information: 1) 

the base module offset number (if offsets were specified); 2) The 

address range covered by the histogram cell (relative to the 

module base if base offsets were used); 3) The percentage of the 

total execution time spent at the address range covered by the 
histogram cell; 4) A line of stars presenting a graphic 
representation of the histogram. 



10.3 P erformance Monitor Control EMT' s 

For most applications the method described above can be used 
to do a performance analysis. However, in special cases (such as 
analizlng the performance of an overlayed program) it is necessary 
to have more explicit control over the performance analysis 
feature as a program is running. The following set of emt ' s may 
be used to control a performance analysis. 

10.3.1 Ini t iali zing A Performance Analysis 

This emt is used to set up parameters that will control a 
performance analysis. It does not actually begin the analysis. 
The forraof the emt is 



-68' 



EMT 37 5 
with RO pointing to the following argument block: 

.BYTE 0,137 

.WORD .base-address 

.WORD .top-address 

.WORD .cell-size 

.WORD .flags 

where .base-address is the address of the base of the region to be 
monitored, .top-address is the address of the top of the region to 
be monitored and .cell-size is the number of bytes to group in 
each histogram cell. If (zero) is specified as the cell size, 
TSX-Plus calculates the cell size to use by dividing the number of 
bytes in the region being monitored (.top-address minus 
.base-address) by the number of cells available in the histogram 
data area (specified when TSX-Plus is generated). The .flags 
parameter is used to control whether I/O wait time is to be 
included in the analysis or not. If a value of 1 is specified as 
the .flags parameter I/O wait time is included in the analysis; if 
a value of (zero) is specified I/O wait time is not included in 
the analysis. 



errors ; 
" 
1 



Code Meaning 

Performance analysis being done by some other user. 

Performance analysis feature not genned into TSX-Plus 



IQ* 3. 2 Starting a. Performance Analysi s 

This emt is used to begin the actual collection of 
performance analysis data. The previous emt must have been 
executed to set up parameters about the performance analysis 
before this emt is done. The form of the emt is 

EMT 37 5 

with RO pointing to the following argument block: 

.BYTE 1,136 

Errors: Code Meaning 

Performance analysis has not been Initialized yet. 
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10*3.3 St opping A Performance Analy si s 

The following emt can be used to suspend the data collection 
for a performance analysis. The data collection can be restarted 
by using the start-analysis emt described above. This emt could, 
for example, be used to suspend the analysis when an overlay 
module Is loaded that Is not to be monitored. The start-analysis 
emt would then be used to reenable the data collection when the 
overlay of Interest Is reloaded. The form of this emt Is 

EMT 375 

with RO pointing to the following argument block: 

.BYTE 2,136 



Errors ; 




Code Meaning 

Performance analysis has not been previously Initialized 



10.3.4 Terminating A Performance Analysl s 

This emt Is used to conclude a performance analysis. It has 
the effect of returning Into a user supplied buffer the results of 
the analysis and freeing the performance analysis feature for use 
by other users. The form of this emt is: 

EMT 37 5 

with RO pointing to the following argument block: 

.BYTE 3,136 

.WORD .parameter-buffer 

.WORD .histogram-buffer 

.WORD .buffer-size 

where .parameter-buffer is the address of a 4 word buffer into 
which will be stored some parameter values describing the analysis 
that was being performed; .histogram-buffer is the address of the 
buffer that will receive the histogram count values; .buffer-size 
is the size (in bytes) of the histogram buffer area. 



Errors: 

1 



Code Meaning 

This job is not doing a performance analysis. 

Area provided for histogram count vector is too small 



The parameter values 
words: 1) Base address of 
monitored region; 3) Hum 

Control and status flagSc 

of bits that provide the following information: 



returned consist of the following 4 
monitored region; 2) Top address of the 
ber of bytes per histogram cell; 4) 
The control and status flags are a set 
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Flag 
1 ' 
100000 



Meanl n 



r/O wait time was included in the analysis. 
Some histogram cell overflowed during the analysis 



The histogram data returned consists of a vector of 16-bit 

binary values -- one value for each cell in the histogram. The 

first value corresponds to the histogram cell that starts with the 

base address of the region that was being monitored. 
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11. TSX-Plus RESTRICTIONS 



11.1 E MT's Not Supported by TSX-Plus 

The following EMT ' s (monitor service requests) are not 
supported by TSX-Plus and are treated as NOP's: .FETCH, .RELEAS, 
.QSET, .CDFN, .INTEN and .SYNCH (.INTEN and .SYNCH nay be used 
within device handlers). Since the .CDFN EMT is not allowed, 
programs must use only channels 0-17. Both version 1 and version 
2 type EMT's are supported by TSX-Plus 
timer support including month and 
.TWAIT and .HRKT erat's. TSX-Plus does 
multi-terminal support emt's. 



TSX-Plus provides full 
year date roll-over and the 
not provide the RT-11 style 



11.2 P rograms Not Supported by T SX-Plus 

Most programs which run under RT-11 will run under TSX-Plus 
without change. However, a modified version of ODT 
( "TSODT"--supplied with TSX-Plus) must be used to debug programs 
under TSX-Plus. The BATCH RT-11 facility is not supported by 
TSX-Plus. 
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APPENDIX A 
DIBOL TSX-Plus SUPPORT SUBROUTINES 



A set of subroutines is provided with TSX-Plus to perform DIBOL 

record locking and message transmission functions. Note that if 

these TSX-Plus features are to be used, they must be enabled when 
the TSX-Plus system is generated. 



1 . Record Locking Subroutines 

The record locking subroutines coordinate access to a common 
file being shared and updated by several TSX-Plus users. The five 
subroutines parallel the operation of the DIBOL statements: OPEN, 
CLOSE, READ, WRITE and UNLOCK. The normal DIBOL I/O statements 
cannot be used to perform record locking under TSX-Plus. 



1 . 1 Opening the file 

The first subroutine is used to open a shared file in update 
•^ode. The form of the call is: 

XCALL FOPEN(chan,devlbl ,errf Ig) 

where 

chan = A decimal expression that evaluates to a number in 
the range 1-15. This is the channel number used in 
associated calls to FREAD, FWRIT, FUNLK and FCLOS 
s ubrout ines . 

devlbl = The name of an alphanumeric literal, field or record 
that contains the file specification in the general 
form: dev : f i Inam. ext 

The file size must not be specified with the file 

name. An optional "/W" switch may be appended to the 

file name to cause the "WAITING FOR dev:file" message 
tobe printed. 

errflg = A numeric variable capable of holding at least two 

digits into which is stored an indication of the 

result of the FOPEN call. The following values are 
returned: 
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value meanl ng 





17 

18 

72 



73 



No error. File is open and ready for access. 

File nane specification is invalid. 

File does not exist or channel is already 

open . 

Too nany channels are open to shared files. 

(Re-gen TSX-Plus and increase the value of 

MAXSFC parameter). 

Too raany shared files are open. (Re-gen 

TSX-Plus and increase the value of HAXSF 

par am e t er ) . 



The FOPEH subroutine should only be used to open files that 
will be updated by several users. The normal DIBOL OPEN READ/WRITE 
sequence should be used for other files. Several files may be 
opened for update by calling FOPEN with different channel numbers. 
The ONERROR DIBOL statement does not apply to these record locking 
subroutines. Instead the "errflg" argument is used to indicate the 
outcome of the operation. 



1 . 2 Locking and reading a. record 

The FREAD subroutine is used to lock and read a record. The 
form of the call is: 

XCALL FREAD(chan, record, rec #,'T' or 'W, errflg) 



where 
chan = 



Decimal expression in the range 1-15 that identifies 
a channel previously opened by FOPEN. 

record = Name of the record or alphanumeric field in which the 
record read is to be placed. 

rec # = Decimal expression that specifies the sequence number 
of the record to be read. This value must be between 
1 and the total number of records in the file. 

'T'/'W = If 'T' is specifed as the fourth parameter, FREAD 
will return a value of 40 in errflg if the requested 
record is locked by some other user. If 'W is 
specified, FREAD will wait until the record is 
unlocked by all other users and will never return the 
record-locked error code. 

errflg = Decimal variable into which is stored one of the 
folio wingvalues: 

val ue meani ng 



No error. Record has been locked and read. 
End-of-file record has been read. 
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Note that although record locking is requested on a 

ecord-by-record basis, the actual locking is done on a 

block-within-f lie basis. (A block contains 512 characters). The 

result of this is that a record is locked if any record contained in 

the same block(s) as the desired record is locked. 

Once a record Is locked and read using FREAD, the record 
remains locked until the program performs one of the following 
operations: 

1. Issues an FWRIT to the channel from which the record was 

read. 

2. Issues another FREAD to the channel. 

3. Issues an FUNLK to the channel. 

4. Issues an FCLOS to the channel. 

5. Terminates execution by use of the STOP statement or because 
o f an error . 



The same set of rules that applies to the DIBOL READ 
apply to FREAD. 



Stat ement 
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1 « 3 Writing a_ record 

The FWRIT subroutine Is called to write a record to a shared 
lie. The form of the call Is: 

XCALL FWRIT(chan, record, rec //,errflg) 

where 

chan « Channel nunber associated with the file. 

record = Name of the record or alphanumeric field that 
contains the record to be written. 

rec // = Decimal expression that specifies the sequence number 
of the record to be written. 

errflg = Decimal variable Into which Is stored one of the 
following values. 

val ue meaning 

No error. 

22 I/O error occurred during write or channel Is 

not open. 
28 Bad record number specified. 

The FWRIT subroutine writes the indicated record to the file 
then unlocks any blocks that were locked by the program. FWRIT 
appends a <CR><LF> to the end of the written record as does the 
JIBOL WRITE statement. The rules for the DIBOL WRITE statement also 
apply to FWRIT. 



1 . 4 Unlocking records 

The FUNLK subroutine is used to unlock records that were locked 
by calling FREAD. The form of the call is: 

XCALL FUNLK(chan) 

chan " Channel number. 



1 . 5 Closing a_ shared file 

The FCLOS subroutine is called to close a channel that was 
previously opened to a shared file by calling FOPEN. The form of 
the call is: 

XCALL FCLOS(chan) 

chan = Channel number. 
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FCLOS unlocks any locked records and closes the file. Other 
users accessing the file are unaffected. After calling FCLOS, the 
channel may be reopened to some other file. 



1 . 6 Record Locking Example 

In the following example a program performs the following 
f unc t i ons : 

1. Opens a shared file named "INV.DAT" on channel 2. 

2. Reads a record whose record number is stored in RECN into 
the field named ITEM and waits if the record is locked by 
another user. 

3. Updates the information in the record. 

4. Revrrites the record to the same position in the file. 

5. Closes the shared file. 

XCALL F0PEN(2, 'INV.DAT' ,ERRFL) 
XCALL FRE AD (2, I TEH, RECN, 'W ,ERRFL) 
;< up date record> 

XCALL FWRIT(2 , ITEM , RECN , ERRFL ) 
XCALL FCL0S(2) 



1 . 7 Modi f ying programs for TSX-Plus 

It is a straightforward process to modify DIBOL programs to use 
the TSX-Plus record locking subroutines. OPEN, CLOSE, READ, WRITE, 
and UNLOCK statements that apply to shared files must be replaced by 
the appropriate subroutine calls. Error conditions must be tested 
by IF statements following the subroutine calls rather than by using 
the ONERROR statement. 

2 . Me ss age Transmi s s i on Subr o ut ines 

Three subroutines are included in the DIBOL support package to 

allow programs to transfer messages to each other. When running 

under TSX-Plus these subroutines must be used instead of the DIBOL 
SEND and RECV statements. 



2 . 1 Message Channels 

Messages are transferred to and from programs by using TSX-Plus 
"Message Channels". A message channel accepts a message from a 
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sending progran, stores the message In a queue associated with the 

channel and delivers the message to a receiving program that 

requests a message from the channel. Message channels are totally 
separate from I/O channels. 

Each active message channel has associated with it a one to six 
character name that Is used by the sending and receiving programs to 
identify the channel. The total number of message channels is 
defined when TSX-Plus is generated. The names associated with the 
channels ate defined dynamically by the running programs. A message 
channel Is said to be "active" if any messages are being held in the 
queue associated with the channel or if any program is waiting for a 
message from the channel. When message channels become inactive 
they are returned to a free pool and may be reused by another 
p rogran . 

The DiBOL SEND command directs a message to a program by using 
the name of the receiving program. Under TSX-Plus, a sending 
program transmits a message using an arbitrary channel name. Any 
program m£iy receive the message by using the same channel name when 
it requests a message. 



2 . 2 Sending a_ Message 

The MSEND subroutine is called to queue a message on a named 
channel. If other messages are already pending on the channel the 
new message is added to the end of the list of waiting messages, 
'heforraofthecallis: 

XCALL MSEND(chan,raessage,errflg) 

where 

chan== alphan urn eric literal or variable that 

contains the channel name (1 to 6 characters). 

message = alphanumeric or decimal literal, field or record that 
contains the message to be sent. 

errflg = Decimal variable into which will be stored one of the 
following values: 

val ue meaning 

Noerror. Message has been sent. 

1 All message channels are busy. (Re-gen TSX-Plus and 
increase the value of HAXMC parameter). 

2 Maximum allowed number of messages are being held in 
message queues. (Re -gen TSX-Plus and Increase the 
value of MAXMSG parameter). 

Note that the maximum message length that may be transferred is 
defined during system generation by the MSCHRS parameter. If a 
•essage longer than this is sent, only the first part of the message 
lllbedelivered. 
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Jl2 Checking for Pending Me s sage s 

The MSGCK subroutine may be called to determine if any messages 
are pending on a named channel. The form of the call is: 

XCALL MSGCK(chan,message,errflg) 



where 

chan = alphanumeric literal or variable that contains the 
of the channel (1 to 6 characters). 



name 



message = alphanumeric or decimal field or record where the 
received message is to be placed. 

errflg = decimal variable into which will be stored one of the 
following valxies: 



value 


3 

If a 



meani ng 

No error. A message has been received. 

No message was queued on the named channel. 



L received message is shorter than the receiving message 
field the remainder of the field is filled with blanks. If the 
message is longer than the field, only the first part of the message 
is received. 



2 . 4 Waiting for a_ Message 

The MSGWT subroutine is used by a receiving program to suspend 
its execution until a message is available on a named channel. It 
is much more efficient for a program to wait for a message by 
calling MSGV/T rather than repeatedly calling MSGCK. The form of the 
c a ]. 1 is: 



XCALL M SGWT(c ha n, message, errflg) 

where the arguments have the same meaning as for MSGCK, 
following values may be returned in errflg. 



and the 



va 1 ue meani ng 

No error. A message has been received. 

1 All message channels are busy. 
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» 5 Me ssage Examp les 

In the following example a program sends a message to another 
program by using a message channel named "SORT" and then waits for a 
reply to come back through a message 



channel named "REPLY". 



XCALL MSENDCSORT' , ' DK : P AYROL . D AT ' ,ERRFL) 
IF(ERRFL.HE.0)GO TO ERROR 
XCALL MSCWTC'REPLY' , MSGBF , ERRFL ) 
IF(ERRFL.NE.0)GO TO ERROR 



3 . U s ing the subrout ines 

The subroutines described above are part of the MACRO program 
called "DTSUB.MAC". Once assembled, the object file for DTSUB 
(DTSUB.OBJ) may be linked with DIBOL programs that use the record 
locking or message facilities. An example of a LINK command is 
shown below. 

.R LINK 

*PROG=PROG, DTSUB, DIBOL 



4 . Miscellaneous Func t i ons 
4 . 1 Determining the TSX-Plus line number 

The TSLIN subroutine can be called to determine the number of 
the TSX-Plus timesharing line from which the program is being run. 
Real lines are numbered consecutively starting at 1 in the same 
order they are specified when TSX-Plus is generated. Detached job 
lines occur next and virtual lines are numbered last. 

The form of the call of TSLIN is: 

XCALL TSLIN(lnum) 

where "Inum" is a numeric variable capable of holding at least two 
digits into which is stored the TSX-Plus line number value. 
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